From 91dd42adfb04ce17ff4644166b4d5f859208d192 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Mon, 5 Feb 2024 02:51:13 +0100 Subject: [PATCH] Documentation: Refinements and improvements --- Makefile | 2 ++ README.md | 64 ++++++++++++++++++++++++++++++------------- docs/backlog.md | 20 ++++++++++++++ docs/conf.py | 37 +++++++++++++++++++++++-- docs/handbook-de.md | 12 ++++---- docs/handbook-en.md | 4 +-- docs/hardware.md | 7 +++++ docs/index.md | 50 +++++++++++++++++++++++++++++++++ docs/requirements.txt | 3 +- docs/sandbox.md | 20 ++++++++++++++ 10 files changed, 190 insertions(+), 29 deletions(-) create mode 100644 docs/backlog.md create mode 100644 docs/hardware.md create mode 100644 docs/sandbox.md diff --git a/Makefile b/Makefile index 1f477f6..6dbd5b6 100644 --- 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 index a164db2..9e34eb7 100644 --- 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.
[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. +
+ [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. +
+ [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 new file mode 100644 index 0000000..f4ee9fa --- /dev/null +++ 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 index 005fd21..d45b125 100644 --- 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 index 805a129..5a2752a 100644 --- 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 index bdc3bf3..842c46d 100644 --- 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 new file mode 100644 index 0000000..6d4ba92 --- /dev/null +++ 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 index 08d6586..a4b62aa 100644 --- 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. +
+[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. +
+ [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. +
+ [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 index 357e9fd..85701a7 100644 --- 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 new file mode 100644 index 0000000..d730025 --- /dev/null +++ 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 +```