diff options
| -rw-r--r-- | Doxyfile | 1 | ||||
| -rw-r--r-- | docs/doxygen-layout.xml | 62 | ||||
| -rw-r--r-- | readme.md | 75 |
3 files changed, 97 insertions, 41 deletions
@@ -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> + @@ -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 |