Skip to content

Implement dual documentation build with Sphinx and ubCode - #34

Draft
Rubyfi wants to merge 1 commit into
mainfrom
sphinx-ubc-parity
Draft

Rubyfi wants to merge 1 commit into
mainfrom
sphinx-ubc-parity

Conversation

@Rubyfi

@Rubyfi Rubyfi commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

This pull request introduces a dual documentation build system, ensuring that documentation is generated and verified using both Sphinx and ubCode (ubc). It updates documentation, build scripts, configuration files, and adds a license. The main goal is to guarantee that both documentation builds have matching content, with automated checks in CI.

Dual documentation build and verification:

  • Added a dual build process in the CI workflow (.github/workflows/pr_checks.yml) to generate documentation with both Sphinx and ubCode, and introduced a parity check to ensure both builds have the same content.
  • Added new scripts: build_doc_ubc.sh for building docs with ubCode, and check_build_parity.py for verifying content parity between the two builds. Updated README.md to document these scripts and explain the dual build process. [1] [2]

ubCode-specific configuration and styling:

  • Added docs/_static/ubc-custom.css to map brand colors and style variables for ubCode’s theme, ensuring visual consistency with the Sphinx (furo) theme.
  • Updated docs/ubproject.toml to configure ubCode’s HTML builder, including theme, logo, CSS, repository links, and PlantUML integration to match Sphinx’s configuration. Also added custom link handling for source code references. [1] [2]

PlantUML update:

  • Updated the PlantUML jar version in docs/conf.py and ubproject.toml to ensure compatibility with both Sphinx and ubCode builds. [1] [2]

Licensing:

  • Added an MIT License file and referenced it in the README.md to clarify project licensing. [1] [2]

@Rubyfi
Rubyfi marked this pull request as draft November 2, 2026 12:29

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.

1 participant