Skip to content

XBND-1399: feat: Standalone community extension

Dylan Hunt requested to merge dylan/feat/sphinx-standalone-plugin into dev

High-Level Proposal*

Related PR: xbe_static_docs!12 (merged)

This repo used to contain both an embedded sphinx_repo_manager sphinx extension and build/deployment logic.

This PR converts this repo into a standalone, community plugin that can be imported into any Sphinx project (+a demo doc repo/layout).

Release Notes*

  • Created standalone sphinx_repo_manager plugin with docs/templates
  • Created Minimalistic demo, doc repo, and manifest
  • Apart from the demos, removed build/deploy logic directly relating to XBE
  • Added support for cloning local git dirs
  • Significantly reduced error redundancy and improved error clarity
    • Now including showing full git CLI commands on err
  • Improve sanitizing when testing locally with secret keys
  • Greatly extended logs when debug_mode set true in the manifest
  • Created a barebones demo_doc
    • Added as the default project to the repo manifest
  • Created a barebones source/_static_docs/index.rst to demonstrate local static docs handling
    • Content here symlinks to content/-/ (for short url slug, similar to how GitLab does it) dashed-url-slug
  • Now supporting Sphinx 8+
  • Meta: Updated this repo's MR template

Media

Build:

build

Extended debug mode (for copy+paste CLI output):

debug_mode

Output:

output


Tests

[x] I tested/built with make html and confirm the expected outcome. [x] Tested building with demo_doc in manifest [x] Tested demo_doc standalone build (without this ext) [x] Tested with source/_static_docs/index.rst -> symlinked fine to content/-/ (same link signatures) [x] Verified build output html display [x] Tested deployment to RTD

Post-Merge TODO

  1. Submit ext to PyPi
  2. Submit ext to Sphinx list of useful repos
Edited by Dylan Hunt

Merge request reports