docs
docs copied to clipboard
Documentation site redux
Summary
This PR migrates the product docs site to a new Sphinx theme, furo, and upgrades Sphinx and its extensions to the latest releases.
Before building this branch for the first time, please make sure you have run pipenv sync --dev
to update Sphinx and its dependencies.
Development Note: Currently building using Python 3.11; however, Mattermost pipelines use Python 3.9. Test all changes against Python 3.9 and Python 3.11 ahead of go-live. When go-live ready, bump pipelines to Python 3.11 to take advantage of incremental improvements.
Remaining work:
- [ ] Remove unnecessary mini-TOC code (..contents)
- [ ] Convert tabbed content syntax (remove
..tabs
)
Hello @neflyte,
Thanks for your pull request! A Core Committer will review your pull request soon. For code contributions, you can learn more about the review process here.
Preview environment failed.
Preview environment failed.
Preview environment failed.
Newest code from cwarnermm has been published to preview environment for Git SHA 2ff4096a35c1e44a4a715fd58827b0f30d8c5d92
/update-branch
Newest code from cwarnermm has been published to preview environment for Git SHA 3d758bf94ecd7939fb3eabc51ef8de37c312f92e
/update-branch
Error trying to update the PR. Please do it manually.
Newest code from cwarnermm has been published to preview environment for Git SHA 98586f9298ece1357ca09792208380f7209f87a1
This PR has been automatically labelled "stale" because it hasn't had recent activity. A core team member will check in on the status of the PR to help with questions. Thank you for your contribution!
Newest code from cwarnermm has been published to preview environment for Git SHA 4c558b40c0c2a9cb9f51c0a2efb905606326db30
This PR has been automatically labelled "stale" because it hasn't had recent activity. A core team member will check in on the status of the PR to help with questions. Thank you for your contribution!
This PR has been automatically labelled "stale" because it hasn't had recent activity. A core team member will check in on the status of the PR to help with questions. Thank you for your contribution!
@asaadmahmood - I've reviewed the merge conflicts and would have resolved them all as "Accept Incoming Change" but I can't directly speak to the changes via mytheme.css
and conf.py
Can you take a look please?
Newest code from cwarnermm has been published to preview environment for Git SHA 88bceb851349e1a9ed7d785a64e11eb5f27e98e7
Newest code from emdecr has been published to preview environment for Git SHA 947c7c7b0f953b7825a5590f52d7db5bd360e7c0
/update-branch
Newest code from cwarnermm has been published to preview environment for Git SHA 28124f2e023b7da23f970e432aa7689fbb4d81e3
I've made a few modifications: :smile:
- Removed the
base.html
template in favour offuro
's built-in base template- It's best to inherit from the
furo
theme as much as possible to keep compatibility
- It's best to inherit from the
- Use Sphinx's
html_baseurl
config option to specify the path of the doc set instead of specifying a PR ID as a custom parameter in thereredirects
extension - GitHub workflows were updated to use the correct
html_baseurl
value for preview environments - Rewrote rST links into
doc
andref
inline directives to allowhtml_baseurl
to work in more places- One-time migration script is included (
convert-links.py
) - Where possible, redirected pages were resolved into their final target links
- Changes were made in a single commit (
[REFACTOR] Rewrite rST links...
) for easier revert if needed - Cleanup:
- Some rST tables need spacing fixes
-
ref
directives may have the incorrect section name and need to be updated
- One-time migration script is included (
- Modified the
search.html
template to inherit frompage.html
; this brings the latest UI updates to the search page
FYI: The modifications to GitHub workflows won't take effect until this PR is merged. Previews created for this PR won't have redirects fixed.
Newest code from cwarnermm has been published to preview environment for Git SHA 62537d03ee9d50d9d149ec022ed8d57cc9682f4f
Note: I've observed that mid-page links (links with URL fragments) don't take the user to the correct part of the page if the announcement banner is showing. Dismissing the banner seems to allow mid-page links to work again.
/update-branch
Newest code from cwarnermm has been published to preview environment for Git SHA 774986ee3e63886decd5b5976dedd134f86d4f95
Newest code from cwarnermm has been published to preview environment for Git SHA 5835eedb3d0f355325ed00f3e57ba3b05f3632b1
Newest code from cwarnermm has been published to preview environment for Git SHA e62e1402a7677e1de27f67d4f0f8fb6a6da9037e
I've got the Edit in GitHub link working; it took a small change in conf.py.
I've also managed to extract the customizations from page.html
into a small set of overrides to furo's page.html
template. :smile:
With regards to Markdown, we can use the doc
and ref
roles in a similar way to rST:
{ref}`Extended Support Release <upgrade/release-definitions:Extended Support Release (ESR)>`
{doc}`Upgrading </upgrade/upgrading-mattermost-server>`
And we can use top-of-page directives like :nosearch:
and :orphan:
in a similar way to Hugo's document frontmatter:
---
nosearch: true
---
(markdown document starts here)
/update-branch
Newest code from cwarnermm has been published to preview environment for Git SHA 2cf26126026f7747b3d9a3ad451ee1382c2fb62e
Newest code from cwarnermm has been published to preview environment for Git SHA a09ee24419bcf07dff3e9536cb6f39695eb7c809