Skip to content

Backport documentation updates to 3df4f0a (v2-edge)#1390

Merged
roosterfish merged 26 commits into
canonical:v2-edgefrom
elijahgreenstein:backport-docs
May 28, 2026
Merged

Backport documentation updates to 3df4f0a (v2-edge)#1390
roosterfish merged 26 commits into
canonical:v2-edgefrom
elijahgreenstein:backport-docs

Conversation

@elijahgreenstein
Copy link
Copy Markdown
Contributor

@elijahgreenstein elijahgreenstein commented May 25, 2026 •
edited
Loading

This PR backports documentation updates from commits 15e4e54 to 3df4f0a (PRs #1362 , #1364, #1368, #1371, #1374, #1382, and #1389), with two exceptions:

Most of the commits in this backport are from the tooling update in #1368. A few edits were made:

  • doc/conf.py was amended to remove the html_extra_path, which is used for Cluster Manager--specific documentation in version 3.
  • URLs for LXD, MicroCeph, and MicroOVN were amended to use the pinned versions (stable-v5.21, v19.2.0-squid and 24.03, respectively).
  • Swagger UI related tooling was removed (specific to MicroCloud 3).
  • A note on snap channels was edited to refer to the LTS release, rather than the feature release.

Checklist

@github-actions github-actions Bot added the Documentation Documentation needs updating label May 25, 2026
roosterfish
roosterfish requested changes May 26, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@roosterfish roosterfish left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, just a few commits regarding the used versions of the linked doc sets.

See https://github.com/canonical/microcloud/blob/v2-edge/doc/Makefile#L13-L16 for the versions we are pinning currently when building the doc sets from git.

Comment thread doc/custom_conf.py Outdated
Comment thread doc/conf.py Outdated
Comment thread doc/.sphinx/_integration/add_config.py Outdated
@elijahgreenstein elijahgreenstein force-pushed the backport-docs branch 2 times, most recently from 2891887 to 286acd7 Compare May 26, 2026 17:19
@elijahgreenstein elijahgreenstein changed the title Backport documentation updates to 52be4e1 (v2-edge) Backport documentation updates to 3df4f0a (v2-edge) May 26, 2026
@elijahgreenstein
Copy link
Copy Markdown
Contributor Author

elijahgreenstein commented May 26, 2026

Thanks for the comments @roosterfish . I've updated the URLs for MicroCeph and MicroOVN to pin the v19.2.0-squid and 24.03 versions of the documentation. I also cherry-picked the commit from my most recently merged PR (#1389), and updated the PR title and message to reflect this.

@elijahgreenstein elijahgreenstein marked this pull request as draft May 27, 2026 04:25
@elijahgreenstein
Copy link
Copy Markdown
Contributor Author

elijahgreenstein commented May 27, 2026

The commit that combined doc/conf.py and doc/custom_conf.py seems to have gotten squashed with another commit while I was rebasing. I'll revisit and get it sorted out.

MggMuggins and others added 20 commits May 27, 2026 11:46
@MggMuggins @elijahgreenstein
doc: Project-aware member shutdown instructions
4ecc979 
Fixes canonical#1361

Signed-off-by: Wesley Hershberger <wesley.hershberger@canonical.com>
(cherry picked from commit 15e4e54)
@elijahgreenstein
doc: update outdated links
98510ab 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 60209ec)

Edited the note in `doc/how-to/install.md` to clarify that the snap
channels shown are the LTS release and to provide a link to the feature
release.

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
@elijahgreenstein
doc: add markdown linter
37e62f6 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit fb72f4f)
@elijahgreenstein
doc: fix lint issues in markdown files
f9145dd 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit a0f1726)
@elijahgreenstein
doc: add documentation organization info to homepage
4751a24 
Add the "How this documentation is organized" section, a required part
of standard Canonical docs home pages.

Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 48d69e3)
@elijahgreenstein
doc: only link to product page in homepage related links
9fe8ab8 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 7aab87c)
@elijahgreenstein
doc/custom_conf.py: Update MicroCeph URL
9603455 
The MicroCeph URL has changed from Read the Docs to
`documentation.ubuntu.com`. This commit updates `custom_conf.py` so that
the MicroCeph `objects.inv` file can be accessed from the new URL.

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
(cherry picked from commit dd6afce)

Edited the MicroCeph URL to point to the documentation for
`v19.2.0-squid`. Edited the MicroOVN URL to use the MicroOVN
documentation site (similar to the LXD and MicroCeph URLs) and point to
version `24.03`.
@elijahgreenstein
doc: remove use of build_requirements.py
a230900 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>

Amended to update gitpython to 3.1.50.

(cherry picked from commit 68bdba7)
@elijahgreenstein
doc: merge conf.py and custom_conf.py
9c05659 
Moves code from custom_conf.py into conf.py and aligns it with the
Sphinx Stack (formerly the Sphinx Starter Pack). This deliberately
excludes the code for the Swagger UI, which will be added into conf.py
in a separate commit to make this change easier to backport to the
v2-edge branch, which does not use Swagger UI.

Signed-off-by: Minae Lee <minae.lee@canonical.com>
Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>

Amended to include update to MicroCeph URL following migration from Read
the Docs to documentation.ubuntu.com.

(cherry picked from commit 407db18)

Edited `intersphinx_mapping` for `SINGLE_BUILD` to use URLs for pinned
versions of LXD (`stable-5.21`), MicroCeph (`v19.2.0-squid`), and
MicroOVN (`24.03`) documentation. Removed `html_extra_path`, as it is
used for the Cluster Manager API (specific to MicroCloud 3).
@elijahgreenstein
doc: merge and update makefile
39a0f68 
Merge Makefile.sp into Makefile and update Makefile to better align with
the Sphinx Stack (formerly the Sphinx Starter Pack).

Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 9dce710)
@elijahgreenstein
doc: replace pyspelling and woke with vale
fdedc05 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 585a3ac)

Amended to remove Swagger UI directories from `doc/.gitignore`, as this
version does not use Swagger UI.

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
@elijahgreenstein
doc: fix vale-flagged spelling/woke issues
2c1da1f 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 5bbacb5)

Amended: removed "SSL" from `.custom_wordlist.txt` (specific to
MicroCloud 3 documentation) and did not add the release notes template.

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
@elijahgreenstein
doc: use canonical-sphinx theme with customizations
b372eab 
Replaces use of the canonical-sphinx-extensions extension with the canonical-sphinx
extension, adapted for MicroCloud customizations. The canonical-sphinx-extensions
package included multiple extensions that have now been split out into their own
extensions and updated, including sphinx-terminal, and these have been re-added as needed.

Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 4827710)
@elijahgreenstein
doc: update use of terminal directive
abae002 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit fa18b47)
@elijahgreenstein
doc: move _templates/ and _static/ to doc/
dae6ffe 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 8536d59)
@elijahgreenstein
doc: use SINGLE_BUILD for linkchecks
141dcde 
Set SINGLE_BUILD=True when running linkcheck to avoid issues in CI where
only MicroCloud is built and linkcheck looks for the integrated docs.

Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit d4bf1e8)
@elijahgreenstein
doc: replace reredirects extension with rerediraffe
ce8127b 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 5b2b7e0)
@elijahgreenstein
doc: update microceph config paths
d6058dd 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 8083e88)

Amended to use the documentation.ubuntu.com MicroCeph URL and to pin the
version to `v19.2.0-squid`.

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
@elijahgreenstein
doc: move substitutions.yaml file
cfc34d7 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit b1b6554)
@elijahgreenstein
doc: consistent use of single quotes in conf.py
714d202 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit af25738)
Minae Lee and others added 6 commits May 27, 2026 14:39
@elijahgreenstein
doc: ignore ubuntu.com in linkcheck
cc74b06 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 0592cb7)
@elijahgreenstein
doc: include integration/microcloud in make clean-integrate
b2c8c1b 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit c73c20c)
@elijahgreenstein
doc: remove RTD search support
f9325c7 
This commit removes the RTD search support, which is already disabled in the
RTD project settings due to inconsistent behavior in the MicroCloud docs.

Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 76b9139)
@elijahgreenstein
doc: add sphinx-stack version
7fdcf68 
Adds a file to record the last version of sphinx-stack the docs tooling
was updated against.

Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 5c89826)
@elijahgreenstein
doc: remove no longer needed workarounds in .readthedocs.yaml
9abb90f 
Signed-off-by: Minae Lee <minae.lee@canonical.com>
(cherry picked from commit 52be4e1)
@elijahgreenstein
doc: link to Sphinx Stack syntax guides
355164b 
This commit brings the MicroCloud documentation into alignment with the
LXD documentation by removing the MyST cheat sheet and instead referring
contributors to Sphinx Stack guides to MyST Markdown and
reStructuredText. This commit also removes a `.wokeignore` file that is
no longer necessary following the removal of the cheat sheet.

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
(cherry picked from commit 3df4f0a)
@elijahgreenstein elijahgreenstein marked this pull request as ready for review May 27, 2026 22:00
@elijahgreenstein
Copy link
Copy Markdown
Contributor Author

elijahgreenstein commented May 27, 2026

@roosterfish , here's the updated PR. I've fixed the Git history and made sure the URLs you flagged are pointing to the pinned versions of LXD, MicroCeph, and MicroOVN. In the process, I also removed some configuration settings and files for Swagger UI, which is specific to MicroCloud 3.

I've updated the PR description to reflect these changes.

roosterfish
roosterfish approved these changes May 28, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@roosterfish roosterfish left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks!

@roosterfish roosterfish merged commit 08989a3 into canonical:v2-edge May 28, 2026
33 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@roosterfish roosterfish roosterfish approved these changes

Assignees

No one assigned

Labels

Documentation Documentation needs updating

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@elijahgreenstein @roosterfish @MggMuggins