Sphinx Integration

pyApp Flow includes integration with Sphinx for documenting steps and workflows.

Installation

The pyApp Flow integration requires autodoc to also be enabled. Add both entries into the extensions variables of your Sphinx docs conf.py file:

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx.ext.autodoc",
    "pyapp_flow.ext.sphinx",
]

Usage

Note

All of these examples can be found in the samples folder in source control.

Document a Step

Document the following step and the autoflow-step directive.

import pyapp_flow as flow

@flow.step(name="Read books from file", output="books")
def read_books(library_path: Path) -> Sequence[Tuple[str, str]]:
    """
    Read book titles and ISBN from data file
    """
    data_file = library_path / "data.txt"
    with data_file.open() as f:
        reader = csv.reader(f)
        return list(reader)

And the Sphinx/ReStructuredText required to generate documentation:

.. autoflow-step:: docs_example.library.read_books

And the resulting documentation:

docs_example.library.read_books()

Read books from file

Read book titles and ISBN from data file

Input Variable(s)

• library_path: Path

Output Variable

• books: Sequence

Options

The noname option prevents the step name from being included in documented output.

Document a Workflow

Next document the workflow that utilises the step

import pyapp_flow as flow

report_books_workflow = (
    flow.Workflow(
        name="Read and print books",
        description="""
        Read books from the library path and print them out to
        the prompt.

        Requires the ``library_path`` to be set.
        """,
    )
    .nodes(
        read_books,
        flow.ForEach("book_title, book_isbn", in_var="books")
        .loop(print_book),
    )
)

And the Sphinx/ReStructuredText required to generate documentation:

.. autoflow-workflow:: docs_example.library.report_books_workflow

And the resulting documentation:

docs_example.library.report_books_workflow()

Read and print books

Read books from the library path and print them out to the prompt.

Requires the library_path to be set.

• Read books from file

• For (book_title, book_isbn) in books

  • loop

    • Print books

Options

The nodes includes a tree of nodes that make up the workflow.

The noname option prevents the workflow name from being included in documented output.