Merge pull request #147 from PrefectHQ/docs-home

jlowin · web-flow · commit 813f17d331bf · 2018-08-19T19:17:37.000-04:00
Update docs home page with license agreement
diff --git a/README.md b/README.md
@@ -24,10 +24,11 @@ Prefect requires Python 3.4+.
 
 ### Install
 
+This will install optional visualization utilities:
 ```bash
 git clone https://github.com/PrefectHQ/prefect.git
 cd prefect
-pip install .
+pip install ".[viz]"
 ```
 
 ## Development
@@ -37,7 +38,7 @@ pip install .
 ```bash
 git clone https://github.com/PrefectHQ/prefect.git
 cd prefect
-pip install -e .[dev]
+pip install -e ".[dev]"
 ```
 
 ### Run unit tests
@@ -49,9 +50,10 @@ pytest
 
 ### Build documentation
 
-To view documentation locally (run this from the root `prefect` directory):
+To view documentation locally:
 
 ```bash
+cd prefect
 yarn docs:dev
 ```
 
diff --git a/docs/README.md b/docs/README.md
@@ -1,30 +1,46 @@
 ---
 home: true
 heroImage: /Logo.svg
-actionText: Get Started →
-actionLink: /introduction
-features:
-  - title: Automate all the things
-    details: If you can do it with Python, you can automate it with Prefect.
-  - title: Test local, deploy global
-    details: Workflows are developed and tested locally, then deployed for execution at scale.
-  - title: Simple but powerful
-    details: Prefect's beautiful API is powered by Dask and Kubernetes, so it's ready for anything.
 footer: Copyright © 2018-present Prefect Technologies, Inc.
 ---
-
-## Prefect
+<div class='hero'>
+    <div style="display: flex;">
+        <p class='action'>
+            <router-link to="introduction.html" class="nav-link action-button">Read the docs</router-link>
+        </p>
+        <p class='action'>
+            <router-link to="agreement.html" class="nav-link action-button">Get the code</router-link>
+        </p>
+    </div>
+    <p style="font-size: 13px; font-style: italic;">
+        Prefect is alpha software under active development by Prefect Technologies, Inc. This early preview is being provided to a limited number of partners to assist with development. By viewing or using the code or documentation, you are agreeing to the <a href='license.html'>alpha software end user license agreement</a>.
+    </p>
+</div>
+
+<div class='features'>
+    <div class='feature'>
+        <h2>Automate all the things</h2>
+        <p>If you can do it with Python, you can automate it with Prefect.</p>
+    </div>
+    <div class='feature'>
+        <h2>Test local, deploy global</h2>
+        <p>Workflows are developed and tested locally, then deployed for execution at scale.</p>
+    </div>
+    <div class='feature'>
+        <h2>Simple but powerful</h2>
+        <p>Prefect's beautiful API is powered by Dask and Kubernetes, so it's ready for anything.</p>
+    </div>
+</div>
+<div class='features' style="padding-bottom: 0px; margin-top: 1em;"></div>
+
+### Prefect
 
 We've reimagined data engineering for the data science era. Prefect is a new workflow management system, designed for modern infrastructure. Users organize `Tasks` into `Flows`, and Prefect takes care of the rest.
 
-Read the [docs](/introduction.html); get the [code](https://github.com/prefecthq/prefect); ask us [anything](mailto:help@prefect.io)!
-
-## License
-
-Prefect is alpha software under active development by Prefect Technologies, Inc. This early preview is being provided to a limited number of partners to assist with development. By viewing or using the code or documentation, you are agreeing to the [alpha software end user license agreement](/license.html).
+Read the [docs](/introduction.html); get the [code](/agreement.html); ask us [anything](mailto:help@prefect.io)!
 
 
-## Hello, world!
+### Hello, world! 👋
 
 ```python
 from prefect import task, Flow
diff --git a/docs/agreement.md b/docs/agreement.md
@@ -0,0 +1,17 @@
+---
+sidebar: false
+editLink: false
+---
+
+# License Agreement
+
+Prefect is alpha software under active development by Prefect Technologies, Inc. This early preview is being provided to a limited number of partners to assist with development. By viewing or using the code, you are agreeing to the [alpha software end user license agreement](license.html).
+
+
+<div class='home' style='padding-top: 0px;'>
+    <div class='hero'>
+        <p class='action'>
+            <a href="https://github.com/PrefectHQ/prefect" class="nav-link action-button">Ok!</a>
+        </p>
+    </div>
+</div>
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
@@ -394,10 +394,29 @@ def generate_coverage():
         "*</sub>".format(short_sha=SHORT_SHA, git_sha=GIT_SHA)
     )
 
+    front_matter = textwrap.dedent(
+        """
+        ---
+        sidebarDepth: 1
+        editLink: false
+        ---
+        """
+    ).lstrip()
+
     shutil.rmtree("api", ignore_errors=True)
     os.makedirs("api", exist_ok=True)
     generate_coverage()
     with open("api/README.md", "w+") as f:
+        f.write(
+            textwrap.dedent(
+                """
+            ---
+            sidebarDepth: 0
+            editLink: false
+            ---
+            """
+            ).lstrip()
+        )
         f.write("# API Reference\n")
         f.write(
             "*This documentation was auto-generated from "
@@ -428,17 +447,7 @@ def generate_coverage():
             os.makedirs(directory, exist_ok=True)
         with open(fname, "w") as f:
             # PAGE TITLE / SETUP
-            f.write(
-                textwrap.dedent(
-                    """
-                    ---
-                    sidebarDepth: 1
-                    editLink: false
-                    ---
-
-                    """
-                ).lstrip()
-            )
+            f.write(front_matter)
             title = page.get("title")
             if title:  # this would be a good place to have assignments
                 f.write(f"# {title}\n---\n")
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -8,36 +8,66 @@ sidebarDepth: 0
 
 Thank you for being one of our early partners. Your feedback is critical to making sure Prefect does everything it's supposed to do. You can always reach us at [help@prefect.io]().
 
-We're very excited to share what we've been working on. This first preview release is `v0.3.0`, and includes all the tools for building, testing, and executing workflows locally.
+We're very excited to share what we've been working on. This first preview release is `0.3.0`, which includes all the tools for building, testing, and executing workflows locally.
 
-You may find a few dead-ends as you poke around the code -- many of those will become functional when we release our server and execution platforms in future preview releases.
+### Overview
 
-## License
+Prefect is a new workflow management system designed for modern data infrastructures.
 
-Prefect is alpha software under active development by Prefect Technologies, Inc. This early preview is being provided to a limited number of partners to assist with development. By viewing or using the code or documentation, you are agreeing to the [alpha software end user license agreement](/license.html).
+Users organize `Tasks` into `Flows`, and Prefect takes care of the rest! With a minimal but expressive API and intelligent defaults, it stays out of your way until you need it.
 
-## Overview
+### What works now 🚀
 
-Prefect is a new workflow management system designed for modern data infrastructures.
+Prefect `0.3.0` is a nearly-complete implementation of Prefect's core workflow logic. We're confident it can be used to design a wide variety of data workflows, and we're ready for you to kick the tires!
 
-Users organize `Tasks` into `Flows`, and Prefect takes care of the rest! With a minimal but expressive API and intelligent defaults, it stays out of your way until you need it.
+This release supports:
+
+- designing custom `Tasks`
+- composing tasks into `Flows` with either a functional or imperative API
+- `FlowRunners` and `TaskRunners` for complete management of the workflow execution process, including all possible state transitions
+- advanced execution patterns including automatic caching, triggers, pausing, dataflow, and retries
+- basic visualization (static GraphViz charts and animated Bokeh applications)
+
+### What's coming soon ⏰
+
+Prefect `0.3.0` does not include a few important features that will be available in future preview releases. Some of those features include:
+
+- our scheduler, server, database, UI, and GraphQL API
+- a standard library of tasks
+- building flows as containers for distribution
+- remote execution clusters
+- Airflow backward-compatibility
+
+Stay tuned for more...
+
+### What we'd love to hear 📢
+
+- Do you have a data engineering or data science use case that can't be expressed with Prefect's design tools?
+- Do you have a use case that **can** be expressed, but you think it could be easier?
+- Are any of our naming conventions or design choices confusing or non-obvious?
+- As we get closer to releasing the platform tools (including UI and API), what features are important to you? How do you want to interact with your data?
+
+Please note that Prefect is alpha software under active development by Prefect Technologies, Inc. This early preview is being provided to a limited number of partners to assist with development. By viewing or using the code or documentation, you are agreeing to the [alpha software end user license agreement](/license.html).
 
 ## "...Prefect?"
 
-From the Latin *praefectus*, meaning "one who is in charge", a prefect is an official who oversees a domain and ensures that work is done correctly.
+From the Latin _praefectus_, meaning "one who is in charge", a prefect is an official who oversees a domain and ensures that work is done correctly.
 
-It also happens to be the name of a roving researcher for that wholly remarkable book, *The Hitchhiker's Guide to the Galaxy*.
+It also happens to be the name of a roving researcher for that wholly remarkable book, _The Hitchhiker's Guide to the Galaxy_.
 
-## Getting Started
+## Installation
 
-### Install Prefect
+:::tip Requirements
 Please note Prefect requires Python 3.4 or higher.
+:::
 
 ```
 git clone https://github.com/PrefectHQ/prefect.git
 cd prefect
-pip install .
+pip install -e ".[viz]"
 ```
+To install all development dependencies (for running unit tests): `pip install -e ".[dev]"`
+
+## What's Next?
 
-### Use Prefect
 Check out our [tutorials](tutorials/) or [API reference docs](api/)... or just `import prefect`.
