Merge pull request #220 from srobo/chore/upgrade-mkdocs

Upgrade mkdocs
srobo · Feb 20, 2025 · 9557825 · 9557825
2 parents 9ddb762 + 4d329e6
commit 9557825
Show file tree

Hide file tree

Showing 15 changed files with 54 additions and 59 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -1,3 +1,8 @@
+---
+hide:
+    - navigation
+---
+
 # Home
 
 Welcome to our runbook. This aims to be a single source for all Student Robotics
@@ -16,7 +21,7 @@ We are always open to new ways to do things, though by recording the reasons
 for our current approach we aim to avoid needing to rediscover that repeatedly.
 
 For more detailed guidance for editors, please see our
-[contribution guide](./contributing.md).
+[contribution guide](./volunteering/contributing-to-the-runbook.md).
 
 ### Scope Limitations
 

diff --git a/docs/competition/competition-roles.md b/docs/competition/competition-roles.md
@@ -31,9 +31,9 @@ Depending on the nature of the event, some of these roles may not be applicable.
 
 ### Arena
 
-- [Marshal](./matches/match-scoring/#match-marshal)
-- [Arena Resetter](./matches/match-scoring/#match-marshal)
-- [Score Entry](./matches/match-scoring/#match-score-entry)
+- [Marshal](./matches/match-scoring.md#match-marshal)
+- [Arena Resetter](./matches/match-scoring.md#match-marshal)
+- [Score Entry](./matches/match-scoring.md#match-score-entry)
 
 ## Team Support
 
@@ -43,14 +43,14 @@ Depending on the nature of the event, some of these roles may not be applicable.
 
 ### Helpdesk
 
-- [Battery Charging](/kit/event-operations/battery-charging.md)
-- [Battery Shuffler](/kit/event-operations/battery-shuffler.md)
+- [Battery Charging](../competition/team-support/battery-charging.md)
+- [Battery Shuffler](../competition/team-support/battery-shuffler.md)
 - [Helpdesker](./team-support/helpdesk.md)
 
 ## Reception
 
 - [Photo Studio Manager](./teams/photo-studio.md)
-- [Photo Studio Helper](./teams/photo-studio.md#photo-studio-helper)
+- [Photo Studio Assistant](./teams/photo-studio.md#photo-studio-assistant)
 - [Crimper](./teams/role-descriptions/crimper.md)
 - [Door Guard](./teams/role-descriptions/door-guard.md)
 - [Kit Return](./team-support/kit-return.md)

diff --git a/docs/competition/competition-setup-roles.md b/docs/competition/competition-setup-roles.md
@@ -12,7 +12,7 @@ Depending on the nature of the event, some of these roles may not be applicable.
 - Setup/Teardown Coordinator
 - Freight Coordinator
 - Tech Setup/Teardown Lead
-- Arena Setup/Teardown Lead ([2016](./arena/sr2016/), [2017](./arena/sr2017/))
+- Arena Setup/Teardown Lead ([2016](./arena/sr2016.md), [2017](./arena/sr2017.md))
 - Pit Setup/Teardown Lead
 
 - Networking

diff --git a/docs/competition/matches/commentating.md b/docs/competition/matches/commentating.md
@@ -17,4 +17,4 @@ Here is a description of the roles related to commentating.
 
 As a commentator you will be stationed near to the arenas and able to walk freely around them. You will be given access to a PA system via a microphone for which to speak through to address the audience. It's important that you do not make announcements to volunteers through this.
 
-Note that as a commentator you may not make decisions about the matches which would otherwise be covered by the [judge](../matches/judging.md#Judge), including determining whether a match is paused or repeated.
+Note that as a commentator you may not make decisions about the matches which would otherwise be covered by the [judge](../matches/judging.md#judge), including determining whether a match is paused or repeated.
diff --git a/docs/competition/production/network/sr2016-network.md b/docs/competition/production/network/sr2016-network.md
@@ -9,7 +9,7 @@ The network at the SR2016 competition will be similar to that deployed
 at the SR2015 competition.
 
 Details of the cabling and cable protection can be found on the
-[cabling page](./sr2016-cabling).
+[cabling page](./sr2016-cabling.md).
 
 ## Network Provision from Newbury Racecourse
 

diff --git a/docs/competition/teams/README.md b/docs/competition/teams/README.md
@@ -7,15 +7,13 @@ original:
 
 This is the documentation for the competition team coordinator role.
 
-There are 7 subordinate roles at the event, each of which is described
+There are various subordinate roles at the event, each of which is described
 in the following documents:
 
-* [Arrival Desk](./role-descriptions/arrival-desk)
-* [Crimper](./role-descriptions/crimper)
-* [Door Guard](./role-descriptions/door-guard)
-* [Intro Briefer](./role-descriptions/intro-briefer)
-* [Kit Return](./role-descriptions/kit-return)
-* [Reception](./role-descriptions/reception)
-* [Tinker](./role-descriptions/tinker)
+* [Crimper](./role-descriptions/crimper.md)
+* [Door Guard](./role-descriptions/door-guard.md)
+* [Kit Return](../team-support/kit-return.md)
+* [Reception](./role-descriptions/reception.md)
+* [Tinker Time](../team-support/tinker-time.md)
 
-**Note: Typically the competition team coordinator role also includes ensuring teams have adequate orientation and information about the rules. A document covering this for the 2017 competition can be found [here](./process-docs/orientation-and-pit-rules).**
+**Note: Typically the competition team coordinator role also includes ensuring teams have adequate orientation and information about the rules. A document covering this for the 2017 competition can be found [here](./process-docs/pit-rules.md).**
diff --git a/docs/infrastructure/competitor-services.md b/docs/infrastructure/competitor-services.md
@@ -11,8 +11,8 @@ The services typically include:
 **Forums**
 :   A space which the competitors can use to chat with each other and with
     mentors and to ask for help with developing their robots.
-    Historically we have used [PHPBB](https://phpbb.com), although from SR2021 
-    onwards we have moved to using Discord with a bot to [gate entry](discord-gated-entry).
+    Historically we have used [PHPBB](https://phpbb.com), although from SR2021
+    onwards we have moved to using Discord with a bot to [gate entry][discord-gated-entry].
 
 **[Code submitter](https://github.com/PeterJCLaw/code-submitter/)**
 :   For the virtual competitions, this is a mechanism for competitors to submit

diff --git a/docs/kit/hardware/kch.md b/docs/kit/hardware/kch.md
@@ -32,7 +32,7 @@ There are 5 green LEDs that are a "progress bar" of boot progress on the KCH. Ea
     - This LED indicates that the filesystem structure on the SD card is valid.
     - It also indicates that the SD card contains a Student Robotics OS image.
 - 60%
-    - This LED is controlled by [`kchd`](../../software/#kch-daemon-kchd) and indicates `kchd` is running.
+    - This LED is controlled by [`kchd`](../software/README.md#kch-daemon-kchd) and indicates `kchd` is running.
     - If this LED has turned on, most of the operating system is loaded and behaving correctly.
 - 80%
     - This LED is turned on when `kchd` has connected to the MQTT broker.
@@ -45,7 +45,7 @@ There are 5 green LEDs that are a "progress bar" of boot progress on the KCH. Ea
 
 The following LEDs are driven by GPIO on the Raspberry Pi and indicate the status of the robot.
 
-All except the `Start` and Heartbeat LED are controlled by [`kchd`](../../software/#kch-daemon-kchd). If `kchd` is not running, these LEDs will not light up. Check the 60% boot progress LED to confirm that `kchd` is running.
+All except the `Start` and Heartbeat LED are controlled by [`kchd`](../software/README.md#kch-daemon-kchd). If `kchd` is not running, these LEDs will not light up. Check the 60% boot progress LED to confirm that `kchd` is running.
 
 - `Code` (Green)
     - Enabled when a USB drive containing a usercode file (`robot.py`) is mounted.
@@ -84,4 +84,4 @@ This jumper shorts the write protect pin on the EEPROM to GND, so that it can be
 
 This 6 pin header located on the left hand side of the board exposes `GND`, and the UART `TX` and `RX` lines from the Raspberry Pi GPIO.
 
-Whilst it's not populated, it may be useful to have it populated on a development board for bootloader debugging.
+Whilst it's not populated, it may be useful to have it populated on a development board for bootloader debugging.
diff --git a/docs/kit/logistics/transport/procedures.md b/docs/kit/logistics/transport/procedures.md
@@ -64,7 +64,7 @@ Some teams may not turn up at Kickstart, therefore leaving their kit uncollected
 
 If a responsible person in attendance at the Kickstart event (for example the Local Kickstart Coordinator) is willing to store the kit for a week or two, and is able to make it available for courier collection, then this is preferable.
 
-If it is not possible to store the kit locally, it must be returned to UK Postbox ASAP. A [Return Shipping Pack](#return-shipping-pack) must be used to package the kit for return. Someone (possibly the venue) will need to make the kit available for courier collection in the day or two following Kickstart.
+If it is not possible to store the kit locally, it must be returned to UK Postbox ASAP. A Return Shipping Pack must be used to package the kit for return. Someone (possibly the venue) will need to make the kit available for courier collection in the day or two following Kickstart.
 
 ## Reallocating kits from drop-outs
 

diff --git a/docs/license.md b/docs/license.md
diff --git a/docs/project-readme.md b/docs/project-readme.md
diff --git a/docs/contributing.md → ...lunteering/contributing-to-the-runbook.md b/docs/contributing.md → ...lunteering/contributing-to-the-runbook.md
@@ -1,12 +1,12 @@
-# Contributing
+# Contributing to the runbook
 
 Contributions to Student Robotics' Runbook should follow Student Robotics'
 [Code of Conduct][code-of conduct] and made under a compatible [license][license].
 
 You may also find the [Zen of Python][pep-20] provides useful guidance.
 
 [code-of conduct]: https://opsmanual.studentrobotics.org/about-the-charity/code-of-conduct
-[license]: ./license.md
+[license]: https://github.com/srobo/runbook/blob/main/LICENSE
 [pep-20]: https://www.python.org/dev/peps/pep-0020/
 
 ## Making big changes
@@ -70,7 +70,7 @@ tools, though may indicate places where those tools should be used.
 The [runbook's homepage][home] has some additional commentary about this.
 
 [srtools]: https://srtools.readthedocs.io/en/latest/
-[home]: ./README.md
+[home]: ../README.md
 
 ### Record reasons
 
@@ -117,7 +117,7 @@ contributing to improved upstream documentation!
 
 `mkdocs` has the power to resolve and validate links, however only when they're
 in a specific format. Links to pages inside the runbook should be relative, and
-end with the `.md` file extension (ie `[some other page](./volunteering/tasks.md)`
-produces [some other page](./volunteering/tasks.md)). This way, `mkdocs` will
+end with the `.md` file extension (ie `[some other page](./tasks.md)`
+produces [some other page](./tasks.md)). This way, `mkdocs` will
 correctly validate these links. Links which don't follow this format are not
 validated.
diff --git a/docs/volunteering/glossary.md b/docs/volunteering/glossary.md
@@ -34,10 +34,10 @@ with "meetings" which are typically where discussions happen
 
 : a development platform, used to host code repositories and to coordinate tasks
 
-[_KCH_](/kit/hardware/kch.md):
+[_KCH_](../kit/hardware/kch.md):
 
 : a [_Raspberry Pi HAT_](https://www.raspberrypi.com/news/introducing-raspberry-pi-hats/) designed
-by Student Robotics that is part of our [_Brain Board_](/kit/hardware/brain-board.md) assembly. KCH
+by Student Robotics that is part of our [_Brain Board_](../kit/hardware/brain-board.md) assembly. KCH
 stands for _Kajetan Champlewski HAT_ in memory of a volunteer.
 
 _Kickstart_:
@@ -57,11 +57,6 @@ _Mentor_:
 
 : a volunteer who helps teams build their robots
 
-_PLOD_:
-
-: an initialism of [_Pink LED of Death_](/kit/hardware/servo-board.md#pink-led-of-death-plod-bug), a
-bug that is present in the Servo Board that can be identified by a pink / purple light on the board.
-
 [_Pull Request (PR)_](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests):
 
 : the review stage of some changes on GitHub to code or documentation

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,16 +4,19 @@ repo_url: https://github.com/srobo/runbook
 strict: true
 edit_uri: edit/main/docs/
 theme:
-  logo:
-    icon: library_books
-  favicon: favicon.ico
   name: material
-  feature:
-    tabs: true
+  icon:
+    logo: fontawesome/solid/book
+  favicon: favicon.ico
   palette:
     primary: 'blue'
     accent: 'blue'
   custom_dir: theme
+  features:
+    - navigation.tabs
+    - navigation.index
+    - content.action.edit
+    - content.action.view
 copyright: |
   Copyright &copy; Student Robotics contributors
   <br>
@@ -25,11 +28,11 @@ copyright: |
 # Customization
 extra:
   social:
-    - type: globe
+    - icon: fontawesome/solid/globe
       link: https://studentrobotics.org
-    - type: github-alt
+    - icon: fontawesome/brands/github-alt
       link: https://github.com/srobo
-    - type: twitter
+    - icon: fontawesome/brands/twitter
       link: https://twitter.com/studentrobotics
 
 # Extensions

diff --git a/requirements.txt b/requirements.txt
@@ -1,13 +1,9 @@
-mkdocs==1.2.2
-mkdocs-material==4.6.3
-mdx-include==1.4.1
-mkdocs-markdownextradata-plugin==0.2.4
-mkdocs-mermaid2-plugin==0.5.2
+mkdocs==1.6.1
+mkdocs-material==9.6.4
+mdx-include==1.4.2
+mkdocs-markdownextradata-plugin==0.2.6
+mkdocs-mermaid2-plugin==1.2.1
 
-# Something in 3.3 (specifically `(3.2.2, 3.3.4]`) breaks mermaid rendering.
-# Haven't looked into what just yet.
-markdown<=3.3
-
-# Jinja2 v3 is breaking for mkdocs. Markupsafe 2.1 is breaking for Jinja2 v2
-jinja2<3
-markupsafe<2.1
+# 4.13.0 deprecates some APIs used by mkdocs-mermaid2-plugin.
+# Pin to an older version to silence warnings.
+beautifulsoup4==4.12.3
Original file line number	Diff line number	Diff line change
Expand Up		@@ -17,4 +17,4 @@ Here is a description of the roles related to commentating.

		As a commentator you will be stationed near to the arenas and able to walk freely around them. You will be given access to a PA system via a microphone for which to speak through to address the audience. It's important that you do not make announcements to volunteers through this.

		Note that as a commentator you may not make decisions about the matches which would otherwise be covered by the [judge](../matches/judging.md#Judge), including determining whether a match is paused or repeated.
		Note that as a commentator you may not make decisions about the matches which would otherwise be covered by the [judge](../matches/judging.md#judge), including determining whether a match is paused or repeated.