🏗️ 💥 Migrate Site Generator to Mkdocs from Sphinx

[ebouchut]

Today we use Sphinx to create and generate the trio-docs website.

🏗️ With this pull-request we switch to Mkdocs (site generation engine) and mkdocs-material (theme).

💥 This PR contains breaking changes.
This is a different toolset.

Updates

• [x] PDF export
• [x] Open external links in a new window (works on docs.diy-trio.org only)
• [x] Add CI/CD to build and publish the site automatically when pushing the dev branch to GitHub
• [x] Document how to install, build, and preview the site locally
• [x] Migrate the Table of Contents (TOC)
• [x] Migrate admonitions (rectangular text boxes)
• [x] Migrate images and their CSS classes
• [x] Migrate Maths formulae
• [x] No ePub export for now. No ad-hoc plugin found.

EDIT: You can take a look at the README on this PR branch if you want to give this branch a whirl

TODO:

• [x] Purple instead of Blue
• [x] TrioDocs instead of Trio documentation
• [x] Move Top-menu to the top row to match LoopDocs for Home, Overview (Device Compatibility could get moved into Overview), Build/Update, User Settings, Optional Settings, Advanced Settings, Resources.
• [x] Move the page sub-menu (page headings) to the right side to match LoopDocs
• Redirect old Sphinx URLs (with en/latest/ prefix) to new ones (without) (won't do)
• [x] Customise the 404 page
• [x] "Integrate" recently merged PRs:
  • [x] #62

  • 73 (not merged)

  • [x] #74
  • [x] #80

  • 81 (not merged)

  • [x] #84
• [x] Merge this PR so that it makes into dev

• [x] Configure a custom sub-domain on GitHub Pages

  • [x] Add a docs/CNAME file containing docs.diy-trio.org
  • [x] Create the gh-pages on this GitHub repository (nightscout/trio-docs` like this:

  It does not exist yet but needs to be created once for the GitHub UI to pick it up in the branch chooser 🐓🥚 :-). Assuming that in your trio-docs repository, the:

  • upstream git remote denotes the nightscout/trio-docs
  • origin git remote denotes your clone of the repository YOUR_USERNAME_HERE/trio-docs Use git remote -v to check if this is the case. FIRST, MAKE SURE to have committed or stashed your current modifications.

    git checkout --orphan gh-pages
    git reset --hard
    git commit --allow-empty -m "fresh and empty gh-pages branch"
    git push upstream gh-pages

    • [x] Configure GitHub Pages
    • [ ] Verify the custom domain
    • Click Your user/company icon at the top right
    • Click Pages
    • Click the "Add a Domain" button
    • Enter diy-trio.org
    • Click the "Add Domain" button to confirm
    • Add a TXT DNS record as explained
    • Click Verify button once done and the DNS modification has been propagated

      

  

  

  • [x] Update the docs.diy-trio.org DNS record after deploying so that it points to GitHub servers IP V4 and V6 addresses. It must be a CNAME record that points to nightscout.github.io (as this is a custom subdomain, not an APEX (main domain)):

    docs.diy-trio.org.  1799    IN      CNAME   nightscout.github.io.

  • [x] Enforce HHTPS
  • [x] Secure the custom domain

[ebouchut]

Using Keyboard Shortcuts to Navigate pages and Search Results

• next page / previous page: N/P
• Open Search box: / or F or S
• In the search results page, use:
  • ↑ ↓ the up and down arrow keys to navigate results
  • ⏎ to open the currently selected search result
  • <Esc> or <Tab> to close the search box

ℹ️ Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#keyboard-shortcuts

[ebouchut]

❓ Hey team, do we need to plan to redirect old ReadTheDocs URLs?

Example:

https://docs.diy-trio.org/en/latest/Getting-Started/Overview.html 
  => https://docs.diy-trio.org/Getting-Started/Overview/

EDIT: Answered here.

[ebouchut]

@tmhastings @MikePlante1 and Team

This PR is now ready for review.

I merged the recent PRs onto this PR branch. Merging (into dev) will go smoothly because it is now a fast-forward without conflict resolution 😅.

IMPORTANT

• Before merging this PR

  • [x] Disable the automation to publish dev to ReadTheDocs (RTD).

• After the merge

  • [x] The remaining tasks (see TODO in the description) include configuring GitHub Pages and modifying a DNS entry. I can help with this if you need me.

[ebouchut]

🙏🏻 @marionbarker

✅ I fixed the typos you found and reported on Discord.