Documentation Quality Assurance

This guide covers the automated checks and tools for maintaining high-quality documentation.

Zero Warnings Policy

NLSQ enforces a zero warnings policy for Sphinx documentation builds. All documentation must build cleanly without errors or warnings.

Status

  • Current State: [PASS] 0 warnings (as of 2025-10-31)

  • Enforcement: Enabled in CI/CD via -W flag

  • Last Major Fix: Documentation ambiguity resolution

Automated Checks

1. CI/CD Pipeline (GitHub Actions)

The documentation workflow (.github/workflows/docs.yml) automatically:

  • Builds Sphinx documentation with warnings treated as errors

  • Checks for broken links in documentation

  • Validates docstring quality with pydocstyle and darglint

  • Tests documentation examples with doctest

  • Measures documentation coverage with interrogate

Key Configuration:

# Build with warnings as errors
make html SPHINXOPTS="-W --keep-going"

Flags:

  • -W: Treat warnings as errors (build fails on warnings)

  • --keep-going: Continue after first warning to show all issues

  • -q: Quiet mode (only show warnings/errors in pre-commit hook)

Important Note: The -n (nitpicky mode) flag is intentionally disabled for scientific computing libraries. Nitpicky mode enforces strict cross-reference checking on all type hints, which is too strict for codebases that use informal type descriptions (e.g., “callable”, “array_like”, “optional”) in docstrings. This pragmatic approach maintains zero-warning standards for actual documentation errors while allowing flexibility in type annotations common in scientific Python code.

2. Pre-commit Hook

A manual pre-commit hook is available for local validation:

# Run documentation build check
pre-commit run --hook-stage manual docs-build --all-files

# Or for specific files
pre-commit run --hook-stage manual docs-build --files docs/guides/workflow_options.rst docs/guides/advanced_customization.rst

Configuration: See .pre-commit-config.yaml

Why Manual? Building full Sphinx docs takes ~2-3 seconds. Making it manual prevents slowing down every commit while still providing easy validation when needed.

Common Documentation Issues

1. RST Table Formatting

Problem: Column text exceeds separator width

============================  # Column separator too short
Scenario
============================
Large datasets (>100K points) # Text overflows

Solution: Widen column separators

==============================  # Widened separator
Scenario
==============================
Large datasets (>100K points)   # Now fits

Alternative: Use grid tables for complex layouts

+=============================+
| Scenario                    |
+=============================+
| Large datasets (>100K pts)  |
+-----------------------------+

2. Ambiguous Cross-References

Problem: Multiple classes with same name

# nlsq/diagnostics.py
class ConvergenceMonitor: ...


# nlsq/utils/diagnostics.py
class ConvergenceMonitor: ...  # Same name!


# In docstring (ambiguous)
"""Uses :class:`ConvergenceMonitor` to track progress."""

Solution: Use fully-qualified names

"""Uses :class:`nlsq.utils.diagnostics.ConvergenceMonitor` to track progress."""

Best Practices

Writing Documentation

  1. Use fully-qualified class references when ambiguity exists

    .. Good
:class:`nlsq.utils.diagnostics.ConvergenceMonitor`

.. Avoid (if ambiguous)
:class:`ConvergenceMonitor`

  2. Test tables locally before committing

    make -C docs html

  3. Follow NumPy docstring style consistently

    def function(param: int) -> str:
    """Short description.

    Longer description paragraph.

    Parameters
    ----------
    param : int
        Parameter description

    Returns
    -------
    str
        Return value description
    """

  4. Keep table columns balanced

    • Use consistent column widths

    • Test with longest expected content

    • Consider grid tables for complex data

Pre-Commit Workflow

# 1. Make documentation changes
vim docs/guides/my_guide.rst

# 2. Test locally (fast)
make -C docs html

# 3. Run pre-commit check (thorough)
pre-commit run --hook-stage manual docs-build --all-files

# 4. Commit if passing
git add docs/guides/my_guide.rst
git commit -m "docs: add my_guide"

Troubleshooting

Build Fails in CI but Passes Locally

Cause: Different Sphinx versions or dependencies

Solution:

# Install dev dependencies
pip install -e ".[dev,docs]"

# Test with CI flags
make -C docs html SPHINXOPTS="-W --keep-going -n"

Pre-commit Hook Fails

Cause: Working directory issues

Solution:

# Ensure you're in project root
cd /path/to/NLSQ

# Verify docs directory exists
ls docs/conf.py

# Run manually for debugging
cd docs && make html SPHINXOPTS="-W --keep-going -n -q"

Many Warnings After Update

Cause: Sphinx or dependency update changed behavior

Solution:

  1. Review warnings in detail: make html 2>&1 | grep WARNING

  2. Fix systematically, one type at a time

  3. Consider adding to .github/fix-commit-errors/ knowledge base

Metrics and Monitoring

Current Documentation Quality

Metric

Target

Current

Status

Sphinx Warnings

0

0

[PASS]

Broken Links

0

0

[PASS]

Doc Coverage

>80%

~70%

[PARTIAL]

Docstring Style

100%

~95%

[PARTIAL]

Historical Context

  • v0.1.5 and earlier: 1036+ warnings (disabled -W flag)

  • v0.1.6 (2025-10-31):

    • Fixed RST table formatting issues

    • Resolved ambiguous cross-references

    • Achieved zero warnings

    • Enabled -W flag in CI

References

See Also