Documentation¶

This guide covers building and contributing to the documentation.

Building Documentation¶

Using just (Recommended)¶

# Build HTML documentation
just docs

# Serve documentation locally
just docs-serve

# Clean documentation build
just docs-clean

Using Sphinx Directly¶

# Build HTML documentation
cd docs
make html

# Serve documentation locally
python -m http.server -d _build/html

# Clean build
make clean

Documentation Structure¶

The documentation is organized into several sections:

docs/
├── index.rst              # Main documentation index
├── features/              # Feature documentation
│   ├── index.rst
│   ├── installation.rst
│   ├── repo-management.rst
│   ├── testing.rst
│   ├── just-commands.rst
│   └── global-options.rst
├── design/                # Design documentation
│   ├── index.rst
│   ├── venv-strategy.rst
│   └── git-operations.rst
├── api/                   # API documentation
│   ├── index.rst
│   ├── core.rst
│   └── commands.rst
└── development/           # Development documentation
    ├── index.rst
    ├── setup.rst
    ├── testing.rst
    ├── documentation.rst
    └── contributing.rst

Writing Documentation¶

reStructuredText Basics¶

Documentation is written in reStructuredText (RST) format:

Section Title
=============

Subsection
----------

**Bold text**
*Italic text*
``Code text``

- Bullet list
- Another item

1. Numbered list
2. Another item

.. code-block:: python

   # Python code example
   def hello():
       print("Hello, world!")

.. note::
   This is a note admonition.

.. warning::
   This is a warning admonition.

Code Examples¶

Use code blocks with syntax highlighting:

.. code-block:: bash

   # Shell commands
   dbx install mongo-python-driver

.. code-block:: python

   # Python code
   import dbx_python_cli

Cross-References¶

Link to other documentation sections:

See :doc:`features/installation` for installation instructions.
See :ref:`section-label` for a specific section.

API Documentation¶

API documentation is auto-generated from docstrings using Sphinx autodoc:

def install_package(repo_path, python_path, install_dir=None):
    """
    Install a package from a directory.

    Args:
        repo_path: Path to the repository root
        python_path: Path to Python executable
        install_dir: Subdirectory to install from (for repos with multiple packages), or None for root

    Returns:
        bool: True if successful, False otherwise
    """

Documentation Style Guide¶

Use clear, concise language - Avoid jargon when possible
Include examples - Show don’t just tell
Use admonitions - Highlight important information with notes/warnings
Keep it up-to-date - Update docs when code changes
Test code examples - Make sure examples actually work
Use consistent formatting - Follow the existing style

Publishing Documentation¶

Documentation is automatically published to Read the Docs on every push to main:

URL: https://dbx-python-cli.readthedocs.io/
Builds: Triggered automatically on push
Versions: Main branch and tagged releases

Local Preview¶

To preview documentation locally before pushing:

# Build and serve
just docs-serve

# Open in browser
open http://localhost:8000