Repository: dbt-labs/dbt-core

Issue:
Make it possible to override "overview" page on docs site
## Feature

### Feature description
Rather than hardcode the overview in the docs site, the overview markdown should live in a docs block. This block should be named something like "__overview__" in the dbt global project. If this docs block is overridden in a project, then the custom overview markdown should be shown in the docs site instead.

### Who will this benefit?
Organizations that want to include custom information for their dbt docs consumers


Discussion:

Resolving patch:
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -24,6 +24,7 @@ def read(fname):
         'dbt': [
             'include/index.html',
             'include/global_project/dbt_project.yml',
+            'include/global_project/docs/*.md',
             'include/global_project/macros/*.sql',
             'include/global_project/macros/**/*.sql',
             'include/global_project/macros/**/**/*.sql',


Test patch:
diff --git a/test/integration/029_docs_generate_tests/test_docs_generate.py b/test/integration/029_docs_generate_tests/test_docs_generate.py
--- a/test/integration/029_docs_generate_tests/test_docs_generate.py
+++ b/test/integration/029_docs_generate_tests/test_docs_generate.py
@@ -3,6 +3,7 @@
 from numbers import Integral
 import os
 from datetime import datetime, timedelta
+from mock import ANY
 
 from test.integration.base import DBTIntegrationTest, use_profile
 from dbt.compat import basestring
@@ -829,7 +830,9 @@ def expected_seeded_manifest(self):
                 'test.test.nothing_model_': [],
                 'test.test.unique_model_id': [],
             },
-            'docs': {},
+            'docs': {
+                'dbt.__overview__': ANY
+            },
             'metadata': {
                 'project_id': '098f6bcd4621d373cade4e832627b4f6',
                 'user_id': None,
@@ -1027,6 +1030,7 @@ def expected_postgres_references_manifest(self):
                 },
             },
             'docs': {
+                'dbt.__overview__': ANY,
                 'test.ephemeral_summary': {
                     'block_contents': (
                         'A summmary table of the ephemeral copy of the seed data'
@@ -1196,7 +1200,9 @@ def expected_bigquery_nested_manifest(self):
                 'model.test.model': ['model.test.seed'],
                 'model.test.seed': []
             },
-            'docs': {},
+            'docs': {
+                'dbt.__overview__': ANY,
+            },
             'metadata': {
                 'project_id': '098f6bcd4621d373cade4e832627b4f6',
                 'user_id': None,
@@ -1304,7 +1310,9 @@ def expected_redshift_incremental_view_manifest(self):
                 "model.test.model": [],
                 "seed.test.seed": ["model.test.model"]
             },
-            'docs': {},
+            'docs': {
+                'dbt.__overview__': ANY,
+            },
             'metadata': {
                 'project_id': '098f6bcd4621d373cade4e832627b4f6',
                 'user_id': None,
@@ -1321,7 +1329,7 @@ def verify_manifest(self, expected_manifest):
         self.assertEqual(
             set(manifest),
             {'nodes', 'macros', 'parent_map', 'child_map', 'generated_at',
-             'docs', 'metadata'}
+             'docs', 'metadata', 'docs'}
         )
 
         self.verify_manifest_macros(manifest)