docs: update copyright, use dynamic version, add explicit Sphinx deps

[jaelliot]

PR: hio — Sphinx Documentation Configuration Updates (2026-01-22)

Summary of Changes

This PR updates the Sphinx documentation configuration to use dynamic versioning, adds explicit dependency pins for reproducible builds, and fixes linting issues.

Configuration Updates (docs/source/conf.py):

• Updated copyright year from 2020-2021 to 2020-2026
• Switched from hardcoded version 0.3.4 to dynamic hio.__version__
• Fixed linting errors:
  • Removed unused sphinx_rtd_theme import (Ruff F401)
  • Moved hio import to top of file (Ruff E402)

Documentation Dependencies (docs/source/requirements.txt):

• Added Sphinx >= 8.1.3
• Added sphinx-rtd-theme >= 3.0.1
• Added ordered-set >= 4.1.0

No Changes Needed:

• sphinx.ext.viewcode already enabled in upstream ioflo/hio
• .readthedocs.yaml already correctly configured for Python 3.13

Testing Performed

cd docs
PYTHONPATH=/path/to/hio/src:$PYTHONPATH make clean
PYTHONPATH=/path/to/hio/src:$PYTHONPATH make html

• Result: ✅ Build succeeded
• Output: build/html/index.html generated successfully
• Warnings: 1485 warnings (RST formatting issues in docstrings, pre-existing)

Known Out-of-Scope Items

The following items were noted during the audit but are not addressed in this PR:

• Docstring Formatting: ~1485 warnings remain regarding RST formatting (definition lists, block quotes) and duplicate object descriptions between autoapi and autodoc. These require changes to source code docstrings across multiple modules.
• Documentation Content: General documentation content updates and improvements are outside the scope of this configuration-focused PR.

[SmithSamuelM]

Is napoleon. (Aka google RST format) doc strings enabled for his? Wondering if that is where the RST errors are coming from.

[jaelliot]

Re: Napoleon and RST Warnings in hio Documentation

Napoleon is currently enabled in hio's Sphinx configuration:

extensions = [
    'sphinx.ext.napoleon',  # Active
    # ...
]
napoleon_include_init_with_doc = True

Build Statistics:

• Total warnings/errors: 1,004
• Errors: 257
• Warnings: 747

Error Breakdown:

1. "Unexpected indentation" (256 errors)

   • Primary issue in docstrings
   • Occurs when code blocks or lists aren't properly formatted for RST
   • Affects: hio.base.doing, hio.base.during, hio.base.filing, and other modules

2. "duplicate object description" (747 warnings)

   • Conflict between autodoc and autoapi extensions
   • Both extensions document the same objects, triggering duplicate warnings
   • Known configuration issue, not docstring formatting

3. Cyclic import warnings (3)

   • Architectural: hio.help.mining and hio.core.uxd.peermemoing

Root Cause:

The docstrings appear to use indentation-based formatting that doesn't align with strict RST syntax requirements. Napoleon parses Google/NumPy style docstrings, but the underlying content still needs proper RST structure for lists, code blocks, and definition lists.

Example from hio.base.doing:

ERROR: Unexpected indentation. [docutils]

These occur where docstrings have code examples or parameter lists without proper RST markup (e.g., :: for code blocks, proper indentation for nested lists).

Observations:

The additional Napoleon settings currently commented out could potentially improve parsing:

# napoleon_use_ivar = True
# napoleon_use_rtype = False  
# napoleon_use_param = False

However, the core issue is structural - the docstrings themselves need RST-compliant formatting. This would require source code updates across multiple modules, which falls outside the scope of configuration changes.

Recommendation:

If improving documentation quality is a priority, addressing these errors would require a systematic docstring refactoring effort. The current PR focuses on configuration fixes (dynamic versioning, dependency pinning) and leaves docstring formatting as a separate initiative. Would you like me to create a tracking issue for the docstring refactoring work, or would you prefer to address this differently?

[SmithSamuelM]

Yes please make a separate tracking issue. No doubt since sphynx has not be working for some time may RST formatting has not been correct. I will need to see the nature of the errors so I can figure out what it’s complaining about since I believe I am largely following the Napolean/Google syntax. Does it still render the doc strings dispite the errors? If it does then we can accept the pull request and then have a background task of cleaning up the RST over time.