Code Documentation

Publish integrates with sphinx.ext.autodoc and sphinx-autoapi to automatically generate documentation from your code.

Docstring Best Practices

We recommend using the Google Style docstrings for clarity and readability.

Example:

def connect_to_database(host: str, port: int) -> bool:
            """
            Connects to the database server.

            Args:
                host (str): The hostname or IP address.
                port (int): The port number.

            Returns:
                bool: True if connection was successful, False otherwise.
            """
            pass
        

Live Example

Here is the documentation for the CollectionDirective class in this project, automatically extracted from the source code:

class photon_platform.publish.directives.collection.CollectionDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SphinxDirective

Directive to insert a collection of articles.

has_content: bool = False

May the directive have content?

option_spec: Dict[str, Any] = {'class': <function unchanged>, 'depth': <function positive_int>, 'hidden': <function flag>, 'limit': <function positive_int>, 'recursive': <function flag>, 'reverse': <function flag>, 'sort': <function unchanged>, 'template': <function unchanged>, 'title': <function unchanged>, 'type': <function unchanged>}

Mapping of option names to validator functions.

run() → List[Node]

Process the collection directive.

Instead of rendering immediately, this method: 1. Discovers all relevant files respecting the Container Boundary Rule. 2. Filters by :type: early before claiming documents in the toctree. 3. Adds them to a hidden toctree so Sphinx knows about them (fixes “not in toctree” warnings). 4. Returns a PendingCollection node to defer rendering until metadata is ready.

Returns:

A list containing the PendingCollection node and a hidden toctree node.