Automatic Documentation¶

Complete guide to generating professional API documentation with Sphinx and reStructuredText.

Getting Started¶

VAST Orbit uses Sphinx for documentation generation and reStructuredText (RST) as the markup language. RST provides clear, readable documentation writing, and Sphinx generates HTML and other formats from RST files.

Learning Path:

Read the reStructuredText (RST) syntax basics below
Explore Sphinx documentation and configuration
Practice with Complete Example
Use Render Your Docstring to preview changes

Tip

The best way to learn is by doing. Create a test project, write RST files, and build documentation with Sphinx.

Environment Setup¶

Complete Sphinx Environment Configuration¶

This section covers setting up Sphinx to automate documentation. (Future: This will be integrated into CI/CD pipeline.)

Step-by-Step Setup:

1. Clone the Repository

git clone https://github.com/vast-data/VAST-Orbit.git
cd vastorbit

2. Create docs Folder

mkdir -p docs

3. Setup Sphinx Environment

Download and unzip the essential Sphinx files (make file and source folder) and place them in the docs folder.

4. Configure conf.py

Edit docs/source/conf.py with special attention to:

copyright year - Update to current year
release version - Match VAST Orbit version
rst_prolog - Content added to top of every RST file (imports, settings)

Example rst_prolog:

rst_prolog = """
.. |vo| replace:: VAST Orbit

.. ipython:: python
   :suppress:

   import vastorbit as vo
   import pandas as pd
   vo.set_option("mode", "full")
"""

5. Install Requirements

pip install -r docs/requirements.txt

6. Install VAST Orbit

# Uninstall existing version if present
pip uninstall vastorbit

# Install from source
pip install .

7. Update Directory Paths

Navigate to docs folder and run:

cd docs
python3 replace_sphinx_dir.py

This updates all directory paths inside VAST Orbit code for Sphinx.

8. Build HTML Documentation

make html

Note

You may need to install make:

apt install make

9. Clean Up Function Names

Remove “vastorbit.” prefix from function names:

python3 remove_pattern.py

This converts vastorbit.VastFrame.bar → VastFrame.bar

10. View Documentation

HTML files are now in docs/build directory.

Quick Rebuild Script¶

For convenience, use the refresh.sh script after making code/docstring changes:

./refresh.sh

Note

You may need to make it executable:

chmod +x refresh.sh

RST Syntax Guide¶

Headers and Subheaders¶

Normal Headers:

Use -------- underneath text to mark as header:

Function Name
-------------

This renders as:

Function Name

Sections and Subsections:

Use ======= for main sections and ------- for subsections:

Parameters
==========
method: str, optional
    Description here.

Subsection
----------
Some text here.

Returns
=======
float
    Return value description.

This renders as:

Parameters

method: str, optional: Description here.

Subsection

Some text here.

Returns

float: Return value description.

Centered Headers:

.. centered:: Some Centered Information!

This renders as:

Some Centered Information!

Indentation and Line Spacing¶

Line spacing and indentation must be carefully managed. Without line breaks, all text is treated as a single line. Use | to go to next line without adding extra space.

Example 1: Using | for compact spacing

Parameters
----------
method: str, optional
    Method used to compute the optimal h.
        | auto : Combination of Freedman Diaconis and Sturges.
        | freedman_diaconis : Freedman Diaconis
        | sturges : Sturges

This renders as:

Parameters

method: str, optional

Method used to compute the optimal h.: auto : Combination of Freedman Diaconis and Sturges.

freedman_diaconis : Freedman Diaconis

sturges : Sturges

(Notice: Each line starts with | and there’s no extra spacing between options)

Example 2: Using blank lines for spacing

Parameters
----------
method: str, optional
    Method used to compute the optimal h.
        auto : Combination of Freedman Diaconis and Sturges.

        freedman_diaconis : Freedman Diaconis

        sturges : Sturges

This renders as:

Parameters

method: str, optional

Method used to compute the optimal h.

auto : Combination of Freedman Diaconis and Sturges.

freedman_diaconis : Freedman Diaconis

sturges : Sturges

(Notice: Extra spacing between each option for better readability)

Example 3: Aligned formatting

Parameters
----------
method: str, optional
    Method used to compute the optimal h.
        auto              : Combination of Freedman Diaconis
                            and Sturges.
        freedman_diaconis : Freedman Diaconis
        sturges           : Sturges

This renders as:

Parameters

method: str, optional

Method used to compute the optimal h.

auto              : Combination of Freedman Diaconis
                    and Sturges.
freedman_diaconis : Freedman Diaconis
sturges           : Sturges

(Notice: Options are aligned for a clean, professional look)

Code Blocks¶

Static Code (Not Executed):

Show code without executing it:

.. code-block:: python

   import vastorbit as vo
   vo.VastFrame({"a":[1,2,3]})

This renders as:

import vastorbit as vo
vo.VastFrame({"a":[1,2,3]})

(Notice: Code is displayed but not executed - just syntax highlighting)

Code Execution¶

Execute and display code using the ipython directive.

Note

Requires extensions in conf.py:

IPython.sphinxext.ipython_directive
IPython.sphinxext.ipython_console_highlighting

Basic Execution:

.. ipython:: python

   import vastorbit as vo
   vo.VastFrame({"a":[1,2,3]})

This renders as:

import vastorbit as vo
vo.VastFrame({"a":[1,2,3]})

(Notice: Code is executed and output is shown, including the VastFrame table)

Suppressing Code/Output¶

Method 1: Suppress Entire Block

Use :suppress: directive option to hide entire code block while still executing it:

.. ipython:: python
   :suppress:

   import vastorbit as vo
   import pandas as pd
   import sys

.. ipython:: python

   print(vo.VastFrame({"a":[1,2,3]}))

This renders as:

print(vo.VastFrame({"a":[1,2,3]}))

(Notice: The import statements are completely hidden - neither code nor output is shown. Only the print statement and its output are visible.)

Method 2: Suppress Single Line

Use @suppress pseudo-directive to hide one line:

.. ipython:: python

   @suppress
   import vastorbit as vo
   print(vo.VastFrame({"a":[1,2,3]}))

This renders as:

@suppress
import vastorbit as vo
print(vo.VastFrame({"a":[1,2,3]}))

(Notice: The import line with @suppress is hidden, but the print output is still shown)

When to Use:

Block suppress (:suppress:): For hiding multiple import statements or setup code
Line suppress (@suppress): For hiding single lines within visible code blocks

Links and References¶

Internal References:

# Section reference
:ref:`api.vastframe`

# Function reference
:py:func:`~vastorbit.VastFrame.bar`

# Module reference
:py:mod:`~vastorbit.VastFrame`

This renders as:

Section reference: VastFrame

Function reference: bar()

Module reference: VastFrame

(Notice: These become clickable links in the HTML documentation)

External Links:

`Link Text <https://example.com>`__

This renders as:

Link Text

Lists¶

Bullet List:

- Item 1
- Item 2
  - Nested item
- Item 3

This renders as:

Item 1
Item 2 - Nested item
Item 3

Numbered List:

First item
Second item
Third item

This renders as:

First item
Second item
Third item

Plotting and Visualizations¶

Matplotlib Plots¶

The @savefig directive saves the matplotlib figure to a file and displays it in the documentation.

How it works:

Create your plot with matplotlib
Add @savefig filename.png on its own line, right before plt.show()
The image is automatically saved to _images/ directory and embedded in the documentation

Example Code:

.. ipython:: python
   :suppress:

   import matplotlib.pyplot as plt

   # Create data
   x = [1, 2, 3, 4, 5]
   y = [2, 4, 6, 8, 10]

   # Create plot
   plt.plot(x, y, marker='o', linestyle='-')
   plt.xlabel('X-axis')
   plt.ylabel('Y-axis')
   plt.title('Simple Linear Plot')

   # Save and display the figure
   @savefig simple_plot.png
   plt.show()

This renders as:

(Notice: The code is hidden by :suppress:, but the plot is displayed. The image is also saved as simple_plot.png)

Key Points about @savefig:

@savefig must be on its own line, immediately before plt.show()
The :suppress: option hides the code from output (shows only the plot)
Images are saved to _images/ directory automatically
The saved image can be reused elsewhere with:
```
.. image:: _images/simple_plot.png
```

Image File Naming Convention¶

Important

Naming Convention for Images:

Format: path_with_underscores_classname_functionname.png

Example: For boxplot function in core/VastFrame/_plotting.py inside vDFPlot class:

core_VastFrame__plotting_vDFPlot_boxplot.png

Multiple plots in one function:

core_VastFrame__plotting_vDFPlot_boxplot_1.png
core_VastFrame__plotting_vDFPlot_boxplot_2.png
core_VastFrame__plotting_vDFPlot_boxplot_3.png

VAST Orbit Plots¶

Matplotlib Backend:

.. ipython:: python
   :suppress:

   import vastorbit as vo
   data = vo.VastFrame({"counts":[1,1,1,2,2,3]})
   @savefig vastorbit_plot.png
   data.bar("counts")

This renders as:

(Notice: VAST Orbit plot saved as PNG and displayed inline)

Plotly Backend:

For Plotly charts, you need to save as HTML and include it:

.. ipython:: python
   :suppress:

   import vastorbit as vo
   vo.set_option("plotting_lib","plotly")
   data = vo.VastFrame({"counts":[1,1,1,2,2,3]})
   fig = data.bar("counts")
   fig.write_html("figures/plotly_bar.html")

.. raw:: html
   :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotly_bar.html

Note

Important Differences:

Matplotlib: Save as PNG with @savefig filename.png
Plotly: Save as HTML with fig.write_html() and include with .. raw:: html

Advanced HTML Output¶

For advanced graphics (VastFrame output, Plotly charts, interactive tables), use this methodology:

Generate HTML representation with ._repr_html_() or .write_html()
Save as HTML file in figures/ directory
Load and display HTML file with .. raw:: html directive

VastFrame Output:

.. ipython:: python
   :suppress:

   import vastorbit as vo
   html_file = open("figures/vastframe_output.html", "w")
   html_file.write(vo.VastFrame({"a":[1,2,3]})._repr_html_())
   html_file.close()

.. raw:: html
   :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/vastframe_output.html

(This embeds the interactive VastFrame table directly in the documentation)

Plotly Correlation Matrix:

.. ipython:: python
   :suppress:

   from vastorbit.datasets import load_titanic
   titanic = load_titanic()
   fig = titanic.corr(method = "spearman")
   fig.write_html("figures/plotly_corr.html")

.. raw:: html
   :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/plotly_corr.html

(This embeds an interactive Plotly correlation heatmap)

HTML File Naming Convention¶

Important

Naming Convention for HTML Files:

Same as images: path_with_underscores_classname_functionname.html

File Paths - Two Different Conventions:

When saving (in Python code): Use relative path "figures/filename.html"
When loading (in raw html directive): Use absolute path /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/filename.html

Example:

# Saving (relative path)
fig.write_html("figures/core_VastFrame_corr.html")

# Loading (absolute path)
.. raw:: html
   :file: /Users/badr.ouali/Documents/VastOrbit-master/docs/figures/core_VastFrame_corr.html

Tables¶

CSV Table Directive¶

Easiest method for creating tables:

.. csv-table:: **Table Title**
   :header: Column Header, Another Column
   :widths: 30, 70

   Row 1 Value, Value in Row 1
   Row 2 Value, Value in Row 2
   Row 3 Value, Value in Row 3

This renders as:

**Table Title**¶
Column Header	Another Column
Row 1 Value	Value in Row 1
Row 2 Value	Value in Row 2
Row 3 Value	Value in Row 3

Manual Table Format¶

More control but more complex:

+---------------+------------------+
| Column Header | Another Column   |
+===============+==================+
| Row 1 Value   | Value in Row 1   |
+---------------+------------------+
| Row 2 Value   | Value in Row 2   |
+---------------+------------------+
| Row 3 Value   | Value in Row 3   |
+---------------+------------------+

This renders as:

Column Header	Another Column
Row 1 Value	Value in Row 1
Row 2 Value	Value in Row 2
Row 3 Value	Value in Row 3

Admonitions and Directives¶

Deprecation Warning¶

.. deprecated:: 3.8
   This feature is deprecated and will be removed in version 4.0.

This renders as:

Deprecated since version 3.8: This feature is deprecated and will be removed in version 4.0.

Notes, Warnings, and More¶

.. note::
   This is a note with important information.

.. tip::
   This is a helpful tip for users.

.. hint::
   This is a hint to guide users.

.. important::
   This is important information that users must know.

.. warning::
   This is a warning about potential issues.

.. danger::
   This is a danger warning for critical situations.

This renders as:

Note

This is a note with important information.

Tip

This is a helpful tip for users.

Hint

This is a hint to guide users.

Important

This is important information that users must know.

Warning

This is a warning about potential issues.

Danger

This is a danger warning for critical situations.

Docstring Standards¶

NumPy Style Template¶

VAST Orbit follows NumPy docstring conventions. Here’s a complete template:

def function_name(param1: str, param2: int = 0) -> dict:
    """
    Brief one-line description of the function.

    Longer description providing more details about the function's
    purpose, behavior, and any important notes. This can span
    multiple lines and include detailed explanations.

    Parameters
    ----------
    param1 : str
        Description of the first parameter. Explain what it does,
        any constraints or requirements, and expected format.
    param2 : int, optional
        Description of the second parameter. Explain its purpose
        and behavior. Default value is 0.

    Returns
    -------
    dict
        Description of the return value. Explain the structure
        and contents of what's returned, including key names
        and value types if returning a dictionary.

    Raises
    ------
    ValueError
        If param1 is empty or invalid.
    TypeError
        If param2 is not an integer.

    Examples
    --------
    Basic usage example:

    .. code-block:: python

       result = function_name("test", 5)
       print(result)

    Advanced usage with actual execution:

    .. ipython:: python

       result = function_name("advanced", param2=10)
       result

    See Also
    --------
    related_function : Brief description of how it relates
    another_function : Another related function
    :py:func:`~vastorbit.module.other_function` : Cross-reference

    Notes
    -----
    Any additional notes, implementation details, algorithm
    explanations, or important considerations for users.

    This section can include:

    - Performance characteristics
    - Edge cases to be aware of
    - Best practices

    References
    ----------
    .. [1] Author Name, "Paper Title", Journal, Year.
    .. [2] Book Author, "Book Title", Publisher, Year.
    """

Best Practices¶

Key Points:

Use NumPy docstring style consistently across all functions
Include complete type hints in function signature (e.g., param: str)
Provide at least one working example that users can copy-paste
Cross-reference related functions with :py:func: directive
Keep descriptions clear, concise, and user-focused
Use proper RST formatting in docstrings (code blocks, lists, etc.)
Test that all examples actually work before committing

Common Sections (in order):

Short Summary - One-line description
Extended Summary - Detailed explanation (optional but recommended)
Parameters - All function arguments with types and descriptions
Returns - What the function returns with type and description
Raises - Exceptions that may be raised (optional)
Examples - Working code examples (at least one required)
See Also - Related functions (optional)
Notes - Additional information (optional)
References - Citations if applicable (optional)

Parameter Description Format:

parameter_name : type
    Description of the parameter. Can span multiple lines
    with proper indentation. Include constraints, default
    behavior, and any important notes.

Example of good vs bad:

Bad:

def process_data(x, y):
    """Process data."""
    return x + y

Good:

def process_data(x: float, y: float) -> float:
    """
    Add two numbers together.

    Parameters
    ----------
    x : float
        First number to add.
    y : float
        Second number to add.

    Returns
    -------
    float
        Sum of x and y.

    Examples
    --------
    .. ipython:: python

       process_data(2.5, 3.5)
    """
    return x + y

Useful Resources¶

reStructuredText (RST):

RST Primer - Official RST basics from Sphinx
RST Directives - Available directives and formatting options
RST Cheat Sheet - Quick reference for common markup
RST Syntax Specification - Complete syntax specification

Sphinx:

Sphinx Domains and Roles - Specialized markup for Python code
Sphinx Configuration - Configure Sphinx behavior
Common RST Substitutions - Reusable content definitions

Python Documentation:

Docutils Documentation - RST parsing library
NumPy Docstring Guide - Standard docstring format we follow
Sphinx Napoleon - Extension for parsing NumPy docstrings

VAST Orbit Specific:

Complete Example - Complete documentation examples
Render Your Docstring - Preview documentation locally

Tip

Learning Strategy:

Start by copying well-documented functions as templates
Check bar() for a reference example
Build documentation locally with make html and preview changes
Compare your rendered output with existing documentation
Iterate until it looks professional and matches the style guide

Automatic Documentation¶

Getting Started¶

Environment Setup¶

Complete Sphinx Environment Configuration¶

Quick Rebuild Script¶

RST Syntax Guide¶

Headers and Subheaders¶

Indentation and Line Spacing¶

Code Blocks¶

Code Execution¶

Suppressing Code/Output¶

Links and References¶

Lists¶

Plotting and Visualizations¶

Matplotlib Plots¶

Image File Naming Convention¶

VAST Orbit Plots¶

Advanced HTML Output¶

HTML File Naming Convention¶

Tables¶

CSV Table Directive¶

Manual Table Format¶

Admonitions and Directives¶

See Also¶

Deprecation Warning¶

Notes, Warnings, and More¶

Docstring Standards¶

NumPy Style Template¶

Best Practices¶

Useful Resources¶