Documentation: Refinements and improvements

hiveeyes · Feb 5, 2024 · cc50d3b · cc50d3b
1 parent 0ac8846
commit cc50d3b
Show file tree

Hide file tree

Showing 10 changed files with 190 additions and 29 deletions.
diff --git a/Makefile b/Makefile
@@ -2,6 +2,7 @@ $(eval venvpath     := .venv)
 $(eval python       := $(venvpath)/bin/python)
 $(eval pip          := $(venvpath)/bin/pip)
 $(eval platformio   := $(venvpath)/bin/platformio)
+$(eval sphinx-autobuild := $(venvpath)/bin/sphinx-autobuild)
 
 setup-virtualenv:
 	@test -e $(python) || python3 -m venv $(venvpath)
@@ -14,3 +15,4 @@ build: setup-virtualenv
 .PHONY: docs
 docs: setup-virtualenv
 	$(pip) install -r docs/requirements.txt -r docs/requirements-dev.txt
+	$(sphinx-autobuild) docs docs/_build/ --open-browser
diff --git a/README.md b/README.md
@@ -1,46 +1,72 @@
-![image](https://github.com/hiveeyes/hanimandl/workflows/PlatformIO%20CI/badge.svg)
-![image](https://img.shields.io/github/v/tag/hiveeyes/hanimandl.svg)
-
 # HaniMandl
 
+![PlatformIO CI](https://github.com/hiveeyes/hanimandl/workflows/PlatformIO%20CI/badge.svg)
+![Documentation](https://readthedocs.org/projects/hanimandl/badge/)
+![Version](https://img.shields.io/github/v/tag/hiveeyes/hanimandl.svg)
+
 [de] Ein halbautomatischer Honig-Abfüll-Roboter.
 <br/>
 [en] A semi-automatic honey filling robot.
 
-- [HaniMandl Documentation]
+[![image](https://community.hiveeyes.org/uploads/default/optimized/2X/4/4cab90a77589485ebf0a2629a05b222a7cf9c84d_2_1380x776.jpeg)
 
-- [Firmware source code repository]
+> [!TIP]
+> The [HaniMandl Documentation] is the canonical source of information about
+> the HaniMandl open source project, and also refers to relevant projects
+> derived from it.
 
-- [Hardware model and design files]
+## Acknowledgements
 
-- [Discussion forum at Hiveeyes]:
+This project would not exist without Marc Vasterling conceiving it,
+and without the countless contributions it received throughout the
+years. Thanks to everyone who contributed, in the order of appearance:
 
-  [de] Viele weitere Informationen, Anleitungen und Handreichungen zum Nachbau des HaniMandl.
+Marc Vasterling, Marc Wetzel, Clemens Gruber, Andreas Holzhammer,
+Marc Junker, Johannes Kuder, Jeremias Bruker, Andreas Motl.
 
-  [en] Lots more information, instructions and handouts for rebuilding the HaniMandl.
 
-- [Facebook group »Imkerei und Technik. Eigenbau«]:
+## Project information
 
-  [de] Weitere Diskussionen über Code, Infos zur Hardware, Fotos, und Videos.
+### Contributions
 
-  [en] More discussions about code, hardware info, photos, and videos.
+Every kind of contribution, feedback, or patch, is much welcome. [Create an
+issue] or submit a patch if you think we should include a new feature, or to
+report or fix a bug.
 
-## Kudos
+### Development
 
-This project would not exist without Marc Vasterling conceiving it,
-and without the countless contributions it received throughout the
-years. Thanks to everyone who contributed, in the order of appearance:
+In order to setup a development environment on your workstation, please head over
+to the [development sandbox] documentation. When you see the software tests succeed,
+you should be ready to start hacking.
 
-Marc Vasterling, Marc Wetzel, Clemens Gruber, Andreas Holzhammer,
-Marc Junker, Johannes Kuder, Jeremias Bruker, Andreas Motl.
+### Software and Hardware
+
+- [Firmware source code repository]
+- [Hardware model and design files]
+
+### Community
+
+- [Discussion forum at Hiveeyes]
+
+  [de] Viele weitere Informationen, Anleitungen und Handreichungen zum Nachbau des HaniMandl.
+  <br/>
+  [en] Lots more information, instructions and handouts for rebuilding the HaniMandl.
+
+- [Facebook group »Imkerei und Technik. Eigenbau«]
+
+  [de] Diskussionen über Code, Infos zur Hardware, Fotos, und Videos.
+  <br/>
+  [en] More discussions about code, hardware info, photos, and videos.
 
-## Licenses
+### License
 
 The HaniMandl firmware is available under the open source "GPLv3"
 license, see [LICENSE] file. For earlier versions and some current
 derivatives, different licenses apply.
 
 
+[Create an issue]: https://github.com/hiveeyes/hanimandl/issues
+[development sandbox]: https://hanimandl.readthedocs.io/en/latest/sandbox.html
 [Discussion forum at Hiveeyes]: https://community.hiveeyes.org/t/hanimandl-halbautomatischer-honig-abfull-roboter/768
 [Facebook group »Imkerei und Technik. Eigenbau«]: https://www.facebook.com/groups/139671009967454
 [Firmware source code repository]: https://github.com/hiveeyes/hanimandl

diff --git a/docs/backlog.md b/docs/backlog.md
@@ -0,0 +1,20 @@
+# Backlog
+
+Various todo items.
+
+## Iteration +1
+- Add kudos
+- Translate handbook into English
+- Nachbau: https://imkerei-pell.at/2019/12/01/hanimandl/
+- Nachbau:
+  - https://gartenhonig.jimdo.com/2020/07/17/hani-mandl/
+  - https://gartenhonig.jimdo.com/2020/10/22/hani-mandl-reloaded/
+- Nachbau: https://www.youtube.com/watch?v=9SggDLuaH_k
+- Fork: https://github.com/ImkereiWetzel/hani-mandl
+- Fork: https://hanimandl.de/
+  - https://www.bayerwaldimker.de/imkereibedarf/honigabf%C3%BCller/
+  - Handbuch: https://www.bayerwaldimker.de/app/download/14574809278/Anleitung_v1.0.pdf?t=1704317396
+  - Videos: https://www.bayerwaldimker.de/imkereibedarf/honigabf%C3%BCller/hanimandl-videos/
+- Fork: https://github.com/RolandRust/HaniMandlWroom
+- Surrogate/placeholder for https://github.com/hiveeyes/hanimandl/blob/main/hani-mandl.ino
+- https://wokwi.com/projects/372863315993780225
diff --git a/docs/conf.py b/docs/conf.py
@@ -7,13 +7,20 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'HaniMandl'
-copyright = '2024, The HaniMandl Developers'
+copyright = '2018-2024, The HaniMandl Developers'
 author = 'The HaniMandl Developers'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["myst_parser"]
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx.ext.intersphinx",
+]
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
@@ -25,3 +32,29 @@
 
 html_theme = 'furo'
 html_static_path = ['_static']
+html_title = "HaniMandl"
+
+
+# -- Options for Sphinx-copybutton -------------------------------------------
+copybutton_remove_prompts = True
+copybutton_line_continuation_character = "\\"
+copybutton_prompt_text = r">>> |\.\.\. |\$ |sh\$ |PS> |cr> |mysql> |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
+
+# -- Options for MyST --------------------------------------------------------
+myst_heading_anchors = 3
+myst_enable_extensions = [
+    "attrs_block",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
diff --git a/docs/handbook-de.md b/docs/handbook-de.md
@@ -1,4 +1,4 @@
-# HaniMandl Handbuch
+# Handbuch [de]
 
 Das HaniMandl Handbuch vermittelt einen Überblick über die Basiskonfiguration
 der HaniMandl Firmware, sowie deren Betrieb.
@@ -230,10 +230,12 @@ Board Heltec ESP32 Arduino > Wifi Kit 32 kompiliert:
 #define USE_ROTARY_SW           // Taster des Rotary benutzen
 ```
 
-> [!TIP]
-> Anleitungen zum Flashen der Binär-Datei gibt es hier:
-> - [HaniMandl 0.2.11 aufspielen]
-> - [HaniMandl 0.2.13 aufspielen]
+```{tip}
+Anleitungen zum Flashen der Binär-Datei gibt es hier:
+
+- [HaniMandl 0.2.11 aufspielen]
+- [HaniMandl 0.2.13 aufspielen]
+```
 
 
 [Heltec WiFi Kit 32]: https://community.hiveeyes.org/t/heltec-wifi-kit-32-esp32-mit-kleinem-oled/1498

diff --git a/docs/handbook-en.md b/docs/handbook-en.md
@@ -1,3 +1,3 @@
-# HaniMandl Handbook
+# Handbook [en]
 
-Todo. In the meanwhile, see the [HaniMandl Handbuch](handbook-de.md).
+Todo. In the meanwhile, see the [](handbook-de.md).
diff --git a/docs/hardware.md b/docs/hardware.md
@@ -0,0 +1,7 @@
+# Hardware
+
+There are multiple variants of the HaniMandl hardware.
+See [Hardware model and design files].
+
+
+[Hardware model and design files]: https://github.com/hiveeyes/hanimandl-hardware
diff --git a/docs/index.md b/docs/index.md
@@ -1,8 +1,58 @@
 # Welcome to HaniMandl
 
+![PlatformIO CI](https://github.com/hiveeyes/hanimandl/workflows/PlatformIO%20CI/badge.svg)
+![Documentation](https://readthedocs.org/projects/hanimandl/badge/)
+![Version](https://img.shields.io/github/v/tag/hiveeyes/hanimandl.svg)
+
+[de] Ein halbautomatischer Honig-Abfüll-Roboter.
+<br/>
+[en] A semi-automatic honey filling robot.
+
+![image](https://community.hiveeyes.org/uploads/default/optimized/2X/4/4cab90a77589485ebf0a2629a05b222a7cf9c84d_2_1380x776.jpeg)
+
+## Documentation
+
 ```{toctree}
 :maxdepth: 1
 
 handbook-de
 handbook-en
+hardware
+sandbox
 ```
+
+
+## Software and Hardware
+
+- [Firmware source code repository]
+- [Hardware model and design files]
+
+
+## Community
+
+- [Discussion forum at Hiveeyes]
+
+  [de] Viele weitere Informationen, Anleitungen und Handreichungen zum Nachbau des HaniMandl.
+  <br/>
+  [en] Lots more information, instructions and handouts for rebuilding the HaniMandl.
+
+- [Facebook group »Imkerei und Technik. Eigenbau«]
+
+  [de] Weitere Diskussionen über Code, Infos zur Hardware, Fotos, und Videos.
+  <br/>
+  [en] More discussions about code, hardware info, photos, and videos.
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+backlog
+```
+
+
+[Discussion forum at Hiveeyes]: https://community.hiveeyes.org/t/hanimandl-halbautomatischer-honig-abfull-roboter/768
+[Facebook group »Imkerei und Technik. Eigenbau«]: https://www.facebook.com/groups/139671009967454
+[Firmware source code repository]: https://github.com/hiveeyes/hanimandl
+[HaniMandl Documentation]: https://hanimandl.readthedocs.io/
+[Hardware model and design files]: https://github.com/hiveeyes/hanimandl-hardware
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
 furo==2024.1.29
-myst-parser>=2,<3
+myst-parser[linkify]>=2,<3
 sphinx>=7,<7.3
+sphinx-copybutton>=0.3.1,<1
diff --git a/docs/sandbox.md b/docs/sandbox.md
@@ -0,0 +1,20 @@
+# Sandbox
+
+This documentation section outlines how to set up and operate
+the development sandbox.
+
+## Acquire Sources
+```shell
+git clone https://github.com/hiveeyes/hanimandl
+cd hanimandl
+```
+
+## Build Firmware
+```shell
+make build
+```
+
+## Build Documentation
+```shell
+make docs
+```