📝 Documentation Guidelines¶

This guide covers best practices for writing effective documentation for CLOE Toolbox components.

Principles of Writing Good Code Documentation¶

Introduction¶

Good documentation is very important for us to to make your code understandable and usable by others (and future you). Here are some tips to help you write useful docs.

Key Principles¶

Keep It Clear and Simple: Use plain language. Avoid jargon unless it’s necessary and explain it if you do use it.
Be Consistent: Stick to the same terms, style, and formatting throughout.
Know Your Audience: Tailor your writing to who will be reading it. For non-professional developers, keep it simple and add plenty of examples.
Cover Everything: Make sure your docs cover all bases – installation, usage, API details, and troubleshooting.
Update Regularly: Keep your documentation up-to-date with any changes in your code.

Structure of Good Documentation for the website¶

Introduction: What does the building block do? Why does it exist?
Getting Started: How to install it and a quick-start guide.
Usage Examples: Practical examples of how to use the code.
API Reference: Detailed info on functions, classes, and methods.
FAQ/Troubleshooting: Common issues and questions.
Contributing: How others can contribute to the project.

Writing Documentation with MkDocs for Material¶

Introduction to MkDocs¶

MkDocs is a tool for creating static websites specifically for documentation. The Material theme makes it look really nice and professional.

Setting Up MkDocs¶

Install MkDocs and the Material Theme:

pip install mkdocs mkdocs-material

Create a New MkDocs Project:

mkdocs new my-project
cd my-project

Using Info Boxes and Code Boxes¶

Info Boxes: Use !!! followed by a type (note, warning, etc.) to create info boxes.

!!! note
    This is an info box.

Code Boxes: Use triple backticks ``` to create code blocks.

```python
def example_function():
    pass
```

Automating Documentation Deployment¶

The default copier Python package template includes an Azure DevOps Pipeline for uploading documentation. To set this up:

Activate the pipeline
Get in touch with CLOE product manager to connect the pipeline.
Configure the pipeline to trigger on commits to your documentation branch.

Chapter 3: Documenting Code within Python¶

Inline Documentation with Docstrings¶

Docstrings are super useful for explaining what your modules, classes, and functions do.

def example_function(param1: int, param2: str) -> bool:
    """
    This function demonstrates an example.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.
    """
    return True

Using Mkdocstrings and Griffe-Fieldz¶

Mkdocstrings: This plugin automatically extracts and renders docstrings in your MkDocs site.
Install mkdocstrings:
```
pip install mkdocstrings
```
Configure mkdocs.yml:
```
plugins:
  - mkdocstrings
```
Add placeholders in your markdown files:
```
::: my_module.my_function
```
Griffe-Fieldz: Enhances mkdocstrings with typing hints and Pydantic field descriptions.
Install griffe-fieldz:
```
pip install griffe-fieldz
```

Integrate with mkdocstrings in mkdocs.yml:

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            annotations_path: docs

Combining Pydantic with Documentation¶

Using Pydantic models helps you generate detailed class documentation without additional effort automatically.

from pydantic import BaseModel, Field

class User(BaseModel):
    id: int = Field(..., description="The unique identifier for a user")
    name: str = Field(..., description="The name of the user")

In your markdown file:

::: my_module.User
    options:
      show_if_no_docstring: true
      members:
        - id
        - name