Skip to content

Improve top-level documentation accuracy and version context - #917

Open
johnjasa wants to merge 6 commits into
docs_guardrailsfrom
update_top_docs
Open

johnjasa wants to merge 6 commits into
docs_guardrailsfrom
update_top_docs

Conversation

@johnjasa

@johnjasa johnjasa commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

Improve top-level documentation accuracy and version context

  1. Align the README with the model overview and remove unsupported capability claims from the intro.
  2. Update contributor, installation, and environment-variable guidance to match current project behavior.
  3. Remove the obsolete unimplemented-features page and revise the H2Integrate design rationale.
  4. Correct Read the Docs metadata, add a latest/stable version selector, and add a changelog page.

Section 1: Type of Contribution

  • Documentation Update

Section 2: Draft PR Checklist

  • Open draft PR
  • Describe the feature that will be added
  • Fill out TODO list steps
  • Describe requested feedback from reviewers on draft PR
  • Complete Section 8: New Model Checklist (if applicable)

Section 3: General PR Checklist

  • PR description thoroughly describes the documentation changes.
  • Added tests for new functionality or bug fixes
  • Tests pass. The documentation build and configured pre-commit checks passed.
  • Documentation
    • Docstrings are up-to-date (not applicable to these documentation changes)
    • Related docs/ files are up-to-date.
    • Documentation has been rebuilt successfully.
    • Examples have been updated (not applicable)
  • CHANGELOG.md
    • At least one complete sentence has been provided to describe the changes made in this PR
    • A PR hyperlink is included as PR TBD pending the PR number.

Section 4: Related Issues

N/A

Section 5: Impacted Areas of the Software

Section 5.1: New Files

  • docs/_static/switcher.json
    • Lists the Read the Docs latest and stable documentation versions.
  • h2integrate/core/docs_sphinx.py
    • Sets the active Read the Docs version and displays the installed H2Integrate package version.

Section 5.2: Modified Files

  • README.md
    • Links to the model overview instead of repeating an inaccurate technology list.
  • docs/_config.yml, docs/_toc.yml
    • Corrects Read the Docs metadata and adds the version selector and changelog page to the book.

Section 6: Additional Supporting Information

The documentation version selector distinguishes the Read the Docs latest and stable builds.
The local build defaults to latest; the site announcement reports the installed H2Integrate
package version. The new changelog page includes the repository changelog.

Section 7: Test Results, if applicable

  • bash docs/build_book.sh: passed with the documentation build configured to treat Sphinx warnings as errors.
  • Targeted pre-commit checks on changed files: passed, including YAML, JSON, Ruff, and whitespace checks.
  • git diff --check: passed.
  • No runtime pytest tests were run. The Sphinx build exercised the documentation extension and pages.

Section 8 (Optional): New Model Checklist

N/A

@johnjasa
johnjasa added this pull request to stack #916 October 8, 2026 18:31
@coveralls

Copy link
Copy Markdown

Coverage Status

Coverage is 81.071% — update_top_docs into docs_guardrails. No base build found for docs_guardrails.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants