Contributing to Documentation

Purpose and Scope

This guide explains how to contribute to the pyjiit documentation. It covers the reStructuredText format, Sphinx autodoc usage, documentation conventions, and the workflow for submitting documentation changes.

For information about the Sphinx configuration and theme setup, see Building Documentation. For details on the automated deployment pipeline, see Documentation Deployment.

Documentation Format and Structure

The pyjiit documentation is written in reStructuredText (.rst files) and built with Sphinx. The documentation sources are located in the docs/ directory and are processed by the sphinx.ext.autodoc extension to automatically extract API documentation from Python docstrings.

Directory Structure

docs/
├── conf.py              # Sphinx configuration
├── index.rst            # Documentation homepage (assumed)
├── usage.rst            # Usage guide with examples
├── apiref.rst           # API reference with autodoc directives
├── _build/              # Generated HTML output (not in version control)
├── _static/             # Static assets (CSS, images)
└── _templates/          # Custom Sphinx templates

Sources: docs/conf.py8-10 docs/usage.rst docs/apiref.rst

reStructuredText Basics

reStructuredText is the markup language used for all documentation files. Here are the key constructs used in pyjiit documentation:

Section Headers

Top Level Header
================

Second Level
------------

Third Level
~~~~~~~~~~~

Code Blocks

Python code examples use the code-block directive:

.. code-block:: Python

   from pyjiit import Webportal

   w = Webportal()
   s = w.student_login("username", "password", CAPTCHA)

Bash commands for installation instructions:

.. code-block:: Bash    

   pip install pyjiit

Sources: docs/usage.rst11-13 docs/usage.rst19-27

Inline Code

Reference code elements inline using :code: role:

The :code:`student_login` method requires three parameters.

Sources: docs/usage.rst47

Notes and Warnings

Important information is highlighted using admonition directives:

.. note::

   Please note that the call to :code:`get_attendance` may take over 10 
   seconds to complete. This wait is from the server so nothing we can do, 
   sadly ;(

Sources: docs/usage.rst105-107

Sphinx Autodoc Usage

The sphinx.ext.autodoc extension automatically generates API documentation from Python docstrings. This ensures the documentation stays synchronized with the code.

Autodoc Directives

The API reference uses these autodoc directives in docs/apiref.rst:

Sources: docs/apiref.rst4-23 docs/conf.py20-23

Autodoc Processing Flow

Example from API Reference:

.. autoclass:: pyjiit.wrapper.Webportal
   :members:

.. automodule:: pyjiit.tokens
   :members:

This configuration:

1. Extracts the Webportal class docstring from pyjiit/wrapper.py
2. Extracts docstrings for all public methods of Webportal
3. Extracts all public members from pyjiit/tokens.py
4. Generates formatted HTML documentation

Sources: docs/apiref.rst4-23 docs/conf.py20-23

Writing Python Docstrings

For autodoc to generate useful documentation, Python source code must contain properly formatted docstrings. The pyjiit codebase uses standard Python docstring conventions.

Class Docstrings

Classes should have a docstring immediately after the class definition:

class Webportal:
    """
    Main driver class for interacting with JIIT Webportal API.

    Provides methods for authentication, attendance queries, exam data,
    and registration information.
    """

Method Docstrings

Methods should document parameters, return values, and exceptions:

def student_login(self, username: str, password: str, captcha: Captcha):
    """
    Authenticate a student and create a session.

    Args:
        username: Student enrollment number
        password: Student password
        captcha: Captcha object for bot protection

    Returns:
        WebportalSession object containing authentication tokens

    Raises:
        LoginError: If authentication fails
        APIError: If the API request fails
    """

Module-Level Docstrings

Modules that are documented with automodule should have a module docstring at the top of the file:

"""
Data models for attendance information.

This module defines AttendanceMeta and AttendanceHeader classes for
representing student attendance data returned by the webportal API.
"""

Sources: docs/apiref.rst10-20

Building Documentation Locally

To test documentation changes before submitting, build the documentation locally.

Prerequisites

1. Python 3.12 (as specified in the workflow)
2. Poetry for dependency management
3. Documentation dependencies installed

Sources: .github/workflows/documentation.yml28-29 .github/workflows/documentation.yml45-49

Build Commands

# Install Poetry if not already installed
pip install poetry

# Install project with documentation dependencies
poetry install --with docs

# Build HTML documentation
poetry run sphinx-build -b html docs docs/_build/html

The --with docs flag installs the docs dependency group, which includes Sphinx and the Furo theme.

Sources: .github/workflows/documentation.yml42-49 .github/workflows/documentation.yml52-53

Viewing the Output

After building, open the generated HTML:

# On Linux/macOS
open docs/_build/html/index.html

# On Windows
start docs/_build/html/index.html

The built documentation will be in the docs/_build/html/ directory.

Sources: .github/workflows/documentation.yml52-54

Local Documentation Development Workflow

Sources: .github/workflows/documentation.yml3-8 .github/workflows/documentation.yml45-53

Documentation Conventions

Tone and Style

The pyjiit documentation uses an informal but informative tone:

• Direct address to the user ("You first get the metadata...")
• Simple explanations ("pretty self-explanatory ig")
• Practical examples with complete code snippets
• Honest about limitations ("This wait is from the server so nothing we can do, sadly ;(")

Sources: docs/usage.rst28 docs/usage.rst105-107

Page Structure

Each documentation page follows this structure:

1. Title - Clear, descriptive section header
2. Purpose - Brief introduction explaining what the page covers
3. Subsections - Organized by topic or workflow
4. Code Examples - Complete, runnable examples
5. Explanations - Step-by-step breakdown of examples
6. Notes/Warnings - Important caveats highlighted

Sources: docs/usage.rst1-145

Code Examples

Code examples should be:

• Complete - Include all necessary imports
• Runnable - Show actual working code
• Commented - Explain key steps inline or in prose
• Output Included - Show expected results

Example structure from docs/usage.rst74-96:

.. code-block:: Python

  # instantiate w = Webportal() and login before this

  meta = w.get_attendance_meta()
  header = meta.latest_header()
  sem = meta.latest_semester()

  print(w.get_attendance(header, sem))

  # Output:
  # {'currentSem': '1',
  #  'studentattendancelist': <FileRef file-url="https://github.com/codelif/pyjiit/blob/0fe02955/{'LTpercantage'#LNaN-LNaN" NaN  file-path="{'LTpercantage'">Hii</FileRef>

### Cross-Referencing

Use the `:code:` role to reference classes, methods, and attributes:

```rst
The :code:`get_attendance_meta()` returns an instance of :code:`AttendanceMeta` object.

Sources: docs/usage.rst99-100

Documentation Configuration

The Sphinx configuration is in docs/conf.py and includes:

The sys.path.insert(0, os.path.abspath('..')) at docs/conf.py10 ensures Sphinx can import the pyjiit package for autodoc.

Sources: docs/conf.py12-23 docs/conf.py33

Submitting Documentation Changes

Testing Before Submission

1. Build locally using the commands above
2. Check for warnings in the Sphinx build output
3. Verify all links work correctly
4. Test code examples to ensure they're accurate
5. Review formatting in the generated HTML

Pull Request Process

1. Commit changes to a feature branch
2. Push to GitHub - This triggers the documentation workflow
3. Create pull request - The workflow builds docs for all branches
4. Review build results - Check the GitHub Actions tab for any errors
5. Merge to main - Only merges to main deploy to GitHub Pages

The documentation workflow runs on:

• All pushes to any branch (builds for validation)
• Pull requests (builds for review)
• Manual triggers (via workflow dispatch)

Only pushes to the main branch trigger deployment to https

Sources: .github/workflows/documentation.yml3-8 .github/workflows/documentation.yml56-63

Automated Build Process

When you submit changes:

The workflow uses:

• Concurrency control to cancel in-progress builds when new commits are pushed
• Caching (keyed by poetry.lock hash) to speed up dependency installation
• peaceiris/actions-gh-pages@v3 for deployment to GitHub Pages

Sources: .github/workflows/documentation.yml10-12 .github/workflows/documentation.yml32-40 .github/workflows/documentation.yml56-63

Common Documentation Tasks

Adding a New Documentation Page

1. Create a new .rst file in the docs/ directory
2. Add appropriate reStructuredText content
3. Reference the page in docs/index.rst (assumed to exist)
4. Build locally to verify
5. Submit via pull request

Documenting a New API Method

1. Add docstring to the method in the Python source
2. The method will automatically appear in the API reference if its class is already documented
3. If it's a new class, add an autoclass directive to docs/apiref.rst
4. Build and verify the documentation renders correctly

Updating Examples

1. Edit the .rst file containing the example (e.g., docs/usage.rst)
2. Test the code to ensure it still works with the current API
3. Update the expected output if the API response format has changed
4. Build locally and verify the example renders correctly

Sources: docs/usage.rst docs/apiref.rst

Troubleshooting Build Issues

Common Errors

Checking Build Output

Sphinx prints warnings and errors during the build:

poetry run sphinx-build -b html docs docs/_build/html

# Look for lines starting with:
# WARNING: ...
# ERROR: ...

All warnings and errors should be resolved before submitting changes.

Sources: .github/workflows/documentation.yml52-53