Publishing on Read the Docs

This repository is already configured for Read the Docs. The live page should be rebuilt from the default branch whenever the package version, user guide, examples, or API docstrings change.

Repository files used by Read the Docs

• .readthedocs.yaml at the repository root selects the builder image and points Sphinx to docs/conf.py.

• docs/conf.py adds src to sys.path and mocks optional/native modules so API pages can be imported without compiling the C++ extension on the docs builder.

• docs/requirements.txt contains documentation-only dependencies.

• docs/index.rst is the documentation landing page and controls the sidebar order.

Recommended update workflow

1. Commit documentation changes together with the code changes they describe.

2. Make sure pyproject.toml and src/hugiml/__init__.py expose the same release version.

3. Run the local Sphinx build before pushing:

   python -m pip install -r docs/requirements.txt
   PYTHONPATH=src sphinx-build -b html docs docs/_build/html
   

4. Push to the default branch used by your Read the Docs project.

5. Open the Read the Docs project dashboard, go to Builds, and trigger a build for latest if the webhook did not start automatically.

6. After the build finishes, open the live documentation and confirm that the footer/title reflects the new version and that the changed pages appear in the sidebar.

Updating the existing hugiml-core RTD page

Your current public page is https://hugiml-core.readthedocs.io/en/latest/. If it still displays an older version after you push, use this checklist:

1. In Read the Docs, open Admin → Advanced Settings and confirm that the default branch matches your GitHub default branch.

2. In Admin → Automation Rules or Admin → Versions, confirm that latest tracks the branch you are updating.

3. In Builds, start a fresh build for latest. If the previous build is cached, choose the option to wipe the build environment before rebuilding.

4. Check the build log for the Git commit SHA. It should match the commit containing the current release docs.

5. If GitHub pushes are not triggering builds, reconnect the GitHub integration or recreate the webhook from the RTD project admin page.

Local build check

Use the same command locally that Read the Docs effectively runs:

python -m pip install -r docs/requirements.txt
PYTHONPATH=src sphinx-build -b html docs docs/_build/html

For a stricter local quality gate, add -W --keep-going. This treats warnings as errors and is useful before releases:

PYTHONPATH=src sphinx-build -b html docs docs/_build/html -W --keep-going

The native _hugiml_core module is mocked for documentation import purposes. This is intentional: docs builds do not need to compile the extension. Runtime tests and wheel validation should still use the normal package build.

PyPI and docs alignment

Before publishing a release, keep these in sync:

• pyproject.toml package version.

• src/hugiml/__init__.py __version__.

• CHANGELOG.md release notes.

• GitHub release or tag, if you use tags for stable documentation versions.

• Read the Docs latest build.

• PyPI project URLs and README content.

After a successful Read the Docs build, verify that the PyPI Documentation project URL and README badge resolve to the updated page.

Troubleshooting

• If API pages fail because optional packages are missing, add the module name to autodoc_mock_imports in docs/conf.py instead of installing heavy runtime extras on Read the Docs.

• If image links fail, confirm that the image is committed under docs/images and referenced with a path relative to the docs directory, such as images/example.png.

• If latest still shows an older release, compare the RTD build log commit SHA with your GitHub commit. A mismatch usually means the RTD project is tracking a different branch or the webhook did not run.

• If a page is missing from the sidebar, add it to the appropriate .. toctree:: in docs/index.rst.