docs
docs copied to clipboard
mattermost
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.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
Newest code from cwarnermm has been published to preview environment for Git SHA 2ff4096a35c1e44a4a715fd58827b0f30d8c5d92
Newest code from cwarnermm has been published to preview environment for Git SHA 3d758bf94ecd7939fb3eabc51ef8de37c312f92e
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
Newest code from cwarnermm has been published to preview environment for Git SHA 28124f2e023b7da23f970e432aa7689fbb4d81e3
I've made a few modifications: :smile:
- Removed the
base.htmltemplate in favour offuro's built-in base template- It's best to inherit from the
furotheme as much as possible to keep compatibility
- It's best to inherit from the
- Use Sphinx's
html_baseurlconfig option to specify the path of the doc set instead of specifying a PR ID as a custom parameter in thereredirectsextension - GitHub workflows were updated to use the correct
html_baseurlvalue for preview environments - Rewrote rST links into
docandrefinline directives to allowhtml_baseurlto 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
refdirectives may have the incorrect section name and need to be updated
- One-time migration script is included (
- Modified the
search.htmltemplate 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.
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)
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