tweak doxygen output

3 files changed, 97 insertions, 41 deletions

diff --git a/Doxyfile b/Doxyfile
index af362dd..3dd7951 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2,6 +2,7 @@
 DOXYFILE_ENCODING = UTF-8
 PROJECT_NAME = "puzzlebox"
 OUTPUT_DIRECTORY = doxygen
+LAYOUT_FILE = docs/doxygen-layout.xml
 
 INPUT += readme.md
 INPUT += lib/mpack
diff --git a/docs/doxygen-layout.xml b/docs/doxygen-layout.xml
new file mode 100644
index 0000000..9ac2aaa
--- /dev/null
+++ b/docs/doxygen-layout.xml
@@ -0,0 +1,62 @@
+<!--
+  This file is largely based off /templates/general/layout_default.xml from
+	<https://github.com/doxygen/doxygen>. The official documentation for this
+	XML file is at <https://www.doxygen.nl/manual/customize.html>.
+-->
+<doxygenlayout version="1.0">
+	<navindex>
+		<tab type="mainpage" visible="yes" title="Index"/>
+		<tab type="topics" visible="yes" title="Components"/>
+	</navindex>
+	<group>
+		<briefdescription visible="yes"/>
+		<detaileddescription visible="yes"/>
+		<groupgraph visible="yes"/>
+		<memberdecl>
+			<nestedgroups visible="yes" title="Components"/>
+			<modules visible="yes"/>
+			<dirs visible="yes"/>
+			<files visible="yes"/>
+			<namespaces visible="yes"/>
+			<concepts visible="yes"/>
+			<classes visible="yes"/>
+			<defines/>
+			<typedefs/>
+			<sequences/>
+			<dictionaries/>
+			<enums/>
+			<enumvalues/>
+			<functions/>
+			<variables/>
+			<signals/>
+			<publicslots/>
+			<protectedslots/>
+			<privateslots/>
+			<events/>
+			<properties/>
+			<friends/>
+			<membergroups visible="yes"/>
+		</memberdecl>
+		<memberdef>
+			<pagedocs/>
+			<inlineclasses/>
+			<defines/>
+			<typedefs/>
+			<sequences/>
+			<dictionaries/>
+			<enums/>
+			<enumvalues/>
+			<functions/>
+			<variables/>
+			<signals/>
+			<publicslots/>
+			<protectedslots/>
+			<privateslots/>
+			<events/>
+			<properties/>
+			<friends/>
+		</memberdef>
+		<authorsection visible="yes"/>
+	</group>
+</doxygenlayout>
+
diff --git a/readme.md b/readme.md
index a6365c0..da96575 100644
--- a/readme.md
+++ b/readme.md
@@ -5,63 +5,56 @@ implemented during the 2023-2024 run of the Puzzlebox project. This year's run
 of the project consists of only software students, and was developed using the
 hardware from the 21-22 run of the project.
 
-Improved hardware was designed but not realised during the 22-23 run of the
-project. This hardware is recommended for future groups participating in the
-project. The software in this repository should be easily portable to various
-other microcontrollers, and a recommendation is made in the [design
-document](docs/design.adoc).
+The software in this repository should be easily portable to various other
+microcontrollers, and a recommendation is made in the [design
+document](docs/design.adoc). Please see the [handover
+document](docs/handover.adoc) first for more details.
+
+> [!NOTE]
+> This project was mostly developed on Linux. All subfolders/modules/libraries
+> use CMake, and *should* build cross-platform when using CMake+Ninja. This has
+> not yet been verified.
 
 ## Documentation
 
-This project is documented using Doxygen. To generate HTML docs, run
+If you are viewing this page from Doxygen, please take a look at the
+[components](topics.html) tab for a comprehensive list of components within
+this project.
+
+Project documentation is available in the [docs](docs/) folder, and all code is
+documented using Doxygen. To generate HTML docs, run
 
 ```
 $ make doxygen
 ```
 
-and open <doxygen/html/index.html> in a browser.
-
-If you are viewing this page from Doxygen, please take a look at
-[topics](/topics.html) for a comprehensive list of components within this
-project.
+and open [the generated HTML files](doxygen/html/index.html) in a browser. A
+rendered copy of this documentation is also hosted unofficially at
+[pipeframe](https://media.pipeframe.xyz/puzzlebox/23-24/doxygen).
 
 ## Tidyness
 
-Please keep this repository tidy by being aware of the following conventions!
+Please keep this repository tidy by being aware of the following conventions:
 
-### Folder structure
-
-```
-/client           desktop PC application for controlling the puzzle box
-/docs             project documentation in AsciiDoc(tor) format
-/lib              custom libraries and submodules
-├───/i2ctcp       I2C over TCP protocol functions (used by main and client)
-├───/mpack        MsgPack CMake configuration and extension
-└───/pbdrv        puzzle bus driver (module driver + (de)serializing functions)
-/main             main controller (RPi pico) software
-/puzzle/<name>    puzzle sources, each puzzle has its own subdirectory
-/shared           (unused) shared code
-/test             unit tests
-```
+- An `.editorconfig` file is provided in this repository. Please install the
+  [EditorConfig](https://editorconfig.org/) plugin for your text editor of
+  choice to automatically use these.
+- There are also `.clang-tidy` and `.clang-format` files, which can be enforced
+  by running
 
-### Code style
-
-An `.editorconfig` file is provided in this repository. Please install the
-[EditorConfig](https://editorconfig.org/) plugin for your text editor of choice
-to automatically use these.
-
-There are also `.clang-tidy` and `.clang-format` files, which can be enforced
-by running
-
-```
-$ make format
-```
+  ```
+  $ make format
+  ```
 
-## Submodules
+## Libraries
 
-This repository tracks (most) dependencies via git submodules.
+Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to
+from each subfolder in the project for convenience (allows CMake to include
+out-of-tree modules). The lib folder contains a mix of direct Git submodules
+and custom libraries specific to this project. (Most) external dependencies are
+tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder.
 
-If something is complaining about missing files
+TL;DR: If something is complaining about missing files
 
 ```
 git submodule update --init --recursive --depth 1