OK CLI Documentation Best Practices¶

Writing Good Docstrings¶

All functions should have docstrings following the Google style:

def generate(type: str, name: str):
    """Generate a component, service, or page.

    Creates a new item from a template, substituting variables
    for the provided name.

    Args:
        type: Type of item to generate (component, service, page)
        name: Name of the item to create

    Returns:
        None

    Raises:
        FileNotFoundError: If the template directory doesn't exist
        ValueError: If the type is invalid

    Example:
        >>> generate("component", "Button")
        # Creates a Button component
    """
    pass

Documentation Structure¶

User Guide¶

For end-users - explain how to use the CLI:

Installation steps
Basic usage examples
Common workflows
Troubleshooting

API Reference¶

For developers - document the code:

Module and class documentation
Function/method signatures
Parameter descriptions
Return values and exceptions

Development¶

For contributors:

Contributing guidelines
Architecture overview
Development setup
Testing procedures

Markdown Best Practices¶

Use Headings Properly¶

# Main Title (H1)
## Section (H2)
### Subsection (H3)
#### Detail (H4)

Code Examples¶

Use fenced code blocks with language:

```python
ok-cli generate component Button
```

```bash
python docs.py build
```

Callouts¶

Use admonitions for important info:

!!! note
    This is a note

!!! warning
    This is a warning

!!! tip
    This is a helpful tip

Tables¶

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Updating Documentation¶

When you make changes to the code:

Update corresponding docstrings
Update user guide if behavior changes
Update API documentation if signatures change
Update changelog with modifications

Building and Testing¶

# Build documentation
python docs.py build

# Serve locally
python docs.py serve

# Clean build
python docs.py clean

Deployment¶

Documentation is automatically deployed when you:

python docs.py deploy

This pushes the site/ directory to the gh-pages branch on GitHub.