Documentation

Documentation is incredibly important to Prefect, both for explaining its concepts to general audiences and describing its API to developers.

Docstrings

Prefect auto-generates API documentation from docstrings by compiling them to Markdown. For details on properly formatting your docstrings, please see the code style guide.

API Reference

Modules, functions, and classes must be explicitly added to the auto-generated documentation. First, update the docs/outline.toml file with the following information: - a header that describes the path to the generated Markdown file - a title for the generated Markdown file - module: an optional path to an importable module, whose docstring will be displayed at the top of the page - classes: an optional list of strings specifying all documented classes in the module - functions: an optional list of strings specifying all documented standalone functions in the module

For example, if the stylized module described above was importable at prefect.utilities.example, then we might add this to outline.toml:

[pages.utilities.example]
title = "Example Module"
module = "prefect.utilities.example"
classes = ["Class"]
functions = ["function"]

Most reference docs sections update their sidebars automatically by detecting the files generated from outline.toml. However, in some instances you may have to include your file explicitly. To do so, update docs/.vuepress/config.js and add it to the appropriate "children" section. The actual prefect.utilities section does auto-update its sidebar, but for the sake of example, you would add the new file to the children array like so:

{
    title: 'prefect.utilities',
    collapsable: true,
    children: [
        'utilities/collections',
        'utilities/example',  // our new file
        ...
    ]
}

Archiving API docs

Whenever a new release of Prefect is cut, we must archive the old API docs so they are available for users using the older versions. To do so, follow these steps:

  • first, make sure you are on the release commit: git checkout $VERSION_TAG
  • next, generate the documentation: cd docs/ && python generate_docs.py
  • push the API docs into a new folder: cd api/ && mv unreleased/ $VERSION_TAG
  • begin tracking any changes to the new folder: git checkout master && git checkout -b new-version-branch && git add $VERSION_TAG
  • lastly, create a new sidebar.js file in the $VERSION_TAG/ folder with an exportable sidebar object (see 0.5.0 for an example)
  • this sidebar will need to be imported into docs/.vuepress/config.js and added to a new dropdown option in the API navigation bar

Concepts

Prefect also includes a great deal of "concept" documentation, which covers features, tutorials, guides, and examples separately from the auto-generated API reference. This page is part of the concept documentation for development! We refer to non-API documentation as Prefect's "Guide".

To write concept docs, simply add Markdown files to the docs/guide directory (or one of its subdirectories). To ensure that your page is displayed in the navigation, edit docs/.vuepress/config.js to include a reference to it.

Semantics

Capitalization

Class Object references should be capitalized; specific instantiations of a Class should only be capitalized at the beginning of a sentence. Example:

myClass = MyClass(*args*) An instantiation of MyClass can is referenced by myClass

Previewing docs locally

Documentation (including both concepts and API references) is built and deployed with every merge to Prefect's master branch. Prior to merge, a GitHub check will allow you to see a hosted version of the documentation associated with every PR.

To preview docs locally, you'll first need to install VuePress and its dependencies. This requires the yarn package manager. You will also need to install the rest of Prefect's dependencies for generating docs. You only need to do this once:

git clone https://github.com/PrefectHQ/prefect.git
cd prefect
yarn install
pip install ".[all_extras]"

To launch a documentation preview:

cd prefect
yarn docs:dev

You'll see a status update as the docs build, and then an announcement that they are available on http://localhost:8080.

Hot-reloading docs

Concept docs will hot-reload every time you save a file, but API reference docs must be regenerated by restarting the server.