Documenting Package & Bricks

Documentation integration is relevant when adding the package into the CODED FLOWS packages repository or creating internal records for local, private packages. The package structure includes documentation in two locations: the README.md file for package-level documentation and the Docs/ directory for individual Brick documentation. Adding or updating documentation is as straightforward as editing these Markdown files with any text editor, no special tools required.

/
├── package.yaml
├── LICENSE
├── README.md                            # <--- Package Doc
├── Bricks/
│   ├── brick_name1.py
│   ├── brick_name2.py
│   └── ... (other Python scripts)
└── Docs/                                # <--- Bricks Docs
    ├── brick_name1.md
    ├── brick_name2.md
    ├── ... (other Markdown files)
    └── images/
        ├── image1.png
        ├── image2.jpg
        └── ... (other image files)

Package Documentation

Adding documentation to the core page of a package is simply a matter of writing it directly in the README.md file.

Bricks Documentation

There are two methods to add documentation for each Brick page:

• Create a Markdown file in the Docs/ folder with the same pythonic name as the Brick. For example, if your Brick is named read_image, the corresponding documentation file should be Docs/read_image.md.
• The second method is simply adding your documentation as a markdown text directly inside the Brick function docstring.

# Example of documentation in docstring
def read_image(...):
    """# Read Image Brick

    This brick loads an image from the specified path using PIL.

    ## Parameters
    - `path`: String path to the image file
    - `mode`: Image mode (default: "RGB")

    ## Returns
    - PIL Image object

    ## Example
    ```python
    img = read_image("path/to/image.jpg")
    ```

    """
    ...