Create default overview block for docs website

MANIFEST.in

@@ -1 +1 @@
-recursive-include dbt/include *.py *.sql *.yml *.html
+recursive-include dbt/include *.py *.sql *.yml *.html *.md

dbt/include/global_project/dbt_project.yml

@@ -2,4 +2,5 @@
 name: dbt
 version: 1.0
 
+docs-paths: ['docs']
 macro-paths: ["macros"]

dbt/include/global_project/docs/overview.md

@@ -0,0 +1,43 @@
+
+{% docs __overview__ %}
+
+### Welcome!
+
+Welcome to the auto-generated documentation for your dbt project!
+
+### Navigation
+
+You can use the `Project` and `Database` navigation tabs on the left side of the window to explore the models
+in your project.
+
+#### Project Tab
+The `Project` tab mirrors the directory structure of your dbt project. In this tab, you can see all of the
+models defined in your dbt project, as well as models imported from dbt packages.
+
+#### Database Tab
+The `Database` tab also exposes your models, but in a format that looks more like a database explorer. This view
+shows relations (tables and views) grouped into database schemas. Note that ephemeral models are _not_ shown
+in this interface, as they do not exist in the database.
+
+### Graph Exploration
+You can click the blue icon on the bottom-right corner of the page to view the lineage graph of your models.
+
+On model pages, you'll see the immediate parents and children of the model you're exploring. By clicking the `Expand`
+button at the top-right of this lineage pane, you'll be able to see all of the models that are used to build,
+or are built from, the model you're exploring.
+
+Once expanded, you'll be able to use the `--models` and `--exclude` model selection syntax to filter the
+models in the graph. For more information on model selection, check out the [dbt docs](https://docs.getdbt.com/reference#section-specifying-models-to-run).
+
+Note that you can also right-click on models to interactively filter and explore the graph.
+
+---
+
+### More information
+
+- [What is dbt](https://docs.getdbt.com/docs/overview)?
+- Read the [dbt viewpoint](https://docs.getdbt.com/docs/viewpoint)
+- [Installation](https://docs.getdbt.com/docs/installation)
+- Join the [chat](https://slack.getdbt.com/) on Slack for live questions and support.
+
+{% enddocs %}

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/integration/029_docs_generate_tests/test_docs_generate.py

@@ -2,6 +2,7 @@
 import json
 import os
 from datetime import datetime, timedelta
+from mock import ANY
 
 from test.integration.base import DBTIntegrationTest, use_profile
 from dbt.compat import basestring
@@ -647,7 +648,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,
@@ -845,6 +848,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'
@@ -1014,7 +1018,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,
@@ -1122,7 +1128,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,
@@ -1139,7 +1147,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)