Loading...

Render Your Docstring

Preview your documentation locally before submitting.

Quick Start

Two Options:

  1. Simple Testing - Test single file (recommended for quick checks)

  2. Full Setup - Complete Sphinx environment (see Sphinx Quickstart)

Simple Testing Setup

Step 1: Download Test Package

Download and unzip the test package in your working directory.

Step 2: Install Requirements

cd docs
pip install -r requirements.txt

Tip

Create a virtual environment first:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 3: Install Make

# Linux/macOS
sudo apt install make

# macOS (alternative)
brew install make

Note

sudo is optional if you have admin rights.

Step 4: Add Your File

Place your Python file inside docs/ and rename it test_file.py.

Note

There’s an example test_file.py already present. Delete it and replace with yours.

Step 5: Build Documentation

make html

Step 6: View Results

Open build/html/index.html in your browser.

# Linux
xdg-open build/html/index.html

# macOS
open build/html/index.html

# Windows
start build/html/index.html

Iterating on Changes

Make Changes → Clean → Rebuild

# 1. Edit test_file.py

# 2. Clean old build
make clean

# 3. Rebuild
make html

# 4. Refresh browser

Quick Rebuild Script:

# Create rebuild.sh
echo "make clean && make html" > rebuild.sh
chmod +x rebuild.sh

# Use it
./rebuild.sh

What to Check

Visual Checks:

  • Function signature displays correctly

  • Parameters formatted properly

  • Code examples render with syntax highlighting

  • Plots/images appear correctly

  • Links work (internal and external)

  • Admonitions (notes, warnings) styled properly

  • Table formatting looks clean

Common Issues:

  • Missing imports - Add to rst_prolog in conf.py

  • Plot not showing - Check file path and @savefig directive

  • Broken links - Verify reference targets exist

  • Code not executing - Check ipython directive syntax

Example test_file.py

"""
Test module for documentation rendering.
"""

def example_function(x: int, y: int = 0) -> int:
    """
    Example function with complete docstring.

    Parameters
    ----------
    x : int
        First parameter
    y : int, optional
        Second parameter. Default is 0.

    Returns
    -------
    int
        Sum of x and y

    Examples
    --------
    .. code-block:: python

       result = example_function(5, 3)
       print(result)
       >>> 8

    .. ipython:: python

       example_function(10, 5)

    See Also
    --------
    other_function : Related function
    """
    return x + y

Troubleshooting

Build Errors:

# Clear cache completely
make clean
rm -rf build/

# Rebuild
make html

Import Errors:

Edit conf.py and add to rst_prolog:

rst_prolog = """
.. ipython:: python
   :suppress:

   import vastorbit as vo
   import sys
   sys.path.insert(0, '/path/to/your/module')
"""

Warnings:

Check build/html/output.txt for detailed warnings and fix accordingly.

Tip

Pro Workflow:

  1. Write docstring in your editor

  2. Copy to test_file.py

  3. Run make clean && make html

  4. Check browser

  5. Iterate until perfect

  6. Copy back to actual file

See also