Documentation

Before building the docs, you’ll want to have pandocs as well as all of the official plugins installed. See Installing Plugins In Development Mode. For most Linux distros, you can install pandocs by

$ sudo apt-get install pandoc

For alternative ways to install, refer to pandocs documentation.

After you have installed the required plugins, you can build the docs by running the script.

$ dffml service dev docs

Python’s built in HTTP server is useful for viewing the documentation.

$ python3 -m http.server --directory pages/ 7000

Examples

Most of the codebase uses the async and await keywords. As such, almost every example block will need to define code that use those keywords within a main coroutine (function defined with async def). We’ll then run that coroutine with the asyncio.run() function.

Example documentation is expected to follow the black formatters code style. black does not yet auto-format example code, so you may want to write the code in a separate file and format it there before copying it into the example.

async def sadd(self, context_handle_string, *args: Input):
    """
    Shorthand for creating a MemoryInputSet with a StringInputSetContext.

    >>> async def main():
    ...     async with MemoryOrchestrator.withconfig({}) as orchestrator:
    ...         async with orchestrator(DataFlow.auto()) as octx:
    ...             await octx.ictx.sadd("Hi")
    >>> asyncio.run(main())
    """

Setup for Example Code

Everything the example code needs must be setup within the tests/test_doctests.py file. It imports all of the files within dffml/ and creates a unittest.TestCase for each class or function with examples. It also creates a temporary directory for the tests to run in.

See that file for more details on doing extra setup and tear down for specific tests.

Doctests

To run all the examples

$ python3 -m unittest tests.test_docstrings

To run a specific example, determine python path to class or function, remove dffml. and change rest of . to _.

$ python3 -m unittest tests.test_docstrings.util_asynctestcase_AsyncTestCase