Documentation guide¶

Great docs make Time-Stream usable and accessible. Help us improve them.

Structure¶

Our documentation is organized as follows:

docs/
├── source/
│   ├── _static/           # Static assets (CSS, images)
│   ├── developer/         # Developer guides (like this one)
│   ├── getting_started/   # Installation and basic usage
│   ├── user_guide/        # In-depth guides for features
│   ├── conf.py            # Sphinx configuration
│   └── index.rst          # Main index page
├── make.bat              # Build commands for Windows
└── Makefile              # Build commands for Unix

Building Documentation¶

To build the documentation:

cd docs
make html

View the result by opening docs/_build/html/index.html in a browser.

Review the build output for warnings and errors.

Creating a New Page¶

To add a new page to the documentation:

Create a new .rst file in the appropriate directory.
Start with a title and introduction, then add any relevant sections for your documentation.
Add the page to the relevant toctree in index.rst.

Including Code Examples¶

Good documentation includes clear code examples. The way we are including code snippets in these documentation is to write Python within actual script files, saved within the src/time_stream/examples directory. The code can then be included in the documentation using the literalinclude block, and executed using the jupyter-execute block.

Code in the example Python file should be organised into individual functions, and use “start-after” and “end-before” markers. This ensures that the literalinclude and jupyter-execute blocks know which bit of code to show/execute.

This approach: 1. Shows the code exactly as it appears in your example file 2. Executes the code and displays its output 3. Keeps example code in maintainable, testable Python files 4. Ensures documentation examples are accurate and up-to-date

Using Markers with `literalinclude`¶

To include specific sections from a file, add marker comments to your code:

import time_stream as ts

def example_function():
    # [start_block_1]
    dates = [datetime(2023, 1, i) for i in range(1, 5)]
    values = [10, 12, 15, 14]

    df = pl.DataFrame({
        "time": dates,
        "temperature": values
    })

    tf = ts.TimeSeries(df=df, time_name="time")
    print(tf)
    # [end_block_1]

Then in your RST file:

.. literalinclude:: ../../../src/time_stream/examples/example.py
   :language: python
   :start-after: [start_block_1]
   :end-before: [end_block_1]
   :dedent:

Key options for literalinclude:

:language: Syntax highlighting language
:start-after: Start including after a specific string
:end-before: Stop including before a specific string
:dedent: Remove indented spaces from each line to make the code snippet in the documentation flush

Executing Code with `jupyter-execute`¶

To show the output of the code snippet, use jupyter-execute and call the function containing the code snippet:

.. jupyter-execute::
   :hide-code:
   import examples
   ts = examples.example_function()

Key options for jupyter-execute:

:hide-code: Show only the output, not the code

Example Workflow¶

Write example code: Create a Python file in src/time_stream/examples
Test the example: Ensure it works correctly
Add marker comments: Add [start_block_X] and [end_block_X] markers
Create documentation: Write an RST file referencing the example
Build and verify: Build the documentation and check the results
Review and refine: Ensure clarity and completeness