[docs] Update with modm_tools docs

Author: salkinium

docs/src/guide/installation.md

@@ -4,11 +4,12 @@ This is the required software for generating, compiling and programming projects
 with modm:
 
 - [Python 3](http://www.python.org/)
-- [Software Construct](http://www.scons.org/)
+- [Software Construct][scons] or [CMake][]
 - [Library Builder][lbuild]
 - AVR toolchain: [avr-gcc][] and [avrdude][]
 - ARM toolchain: [gcc-arm-toolchain][] and [OpenOCD][].
-- [Doxygen](http://www.doxygen.nl)
+- Optional: [Doxygen][] or [Doxypress][]
+- Optional: [gdbgui][] for IDE-independent debugging
 
 Note that the modm examples use the SCons build system by default, however,
 you are not *required* to use it. See [the reference manual](../../reference/build-systems) for
@@ -48,11 +49,17 @@ well:
 	brew install arm-gcc-bin
 	brew install openocd --HEAD
 
-scons now works with Python 3. Unfortunately, macOS still defaults to Python 2.
+We recommend the use of a graphical frontend for GDB called [gdbgui][]:
+
+	pip3 install gdbgui
+
+SCons now works with Python 3. Unfortunately, macOS still defaults to Python 2.
 For a less intrusive way to run all scons scripts with Python 3 add this to your
 `.bashrc` or `.zshrc`:
 
 	alias scons="/usr/bin/env python3 $(which scons)"
+	# or if your using scons elsewhere too:
+	alias scons3="/usr/bin/env python3 $(which scons)"
 
 To compile modm *for macOS* (and not the embedded target) you need to install
 some of these libraries as well, depending on what modm modules you use:
@@ -81,12 +88,16 @@ Install the AVR toochain:
 !!! bug "avr-gcc on Ubuntu"
 	Ubuntu does not provide an up-to-date version of avr-gcc that supports C++17.
 	For our CI we've created a [precompiled version of avr-gcc for Ubuntu][avr-gcc-latest].
-	Use at your own risk.
+	Unfortunately its path is hardcoded to `/work/avr-gcc`.
 
 Install the ARM toochain by downloading [the pre-built version][gcc-arm-toolchain]
 for 64-bit Linux and adding its `/bin` directory to your path.
-Even though your distribution may ship their own ARM toolchain, we *very strongly
-recommend* using the official toolchain, since all of modm is tested with it.
+**Even though your distribution may ship their own ARM toolchain, we very strongly
+recommend using the official toolchain, since all of modm is tested with it.**
+
+We recommend the use of a graphical frontend for GDB called [gdbgui][]:
+
+	pip3 install gdbgui
 
 To compile modm *for Linux* (and not the embedded target) you need to install
 some of these libraries as well, depending on what modm modules you use:
@@ -96,32 +107,49 @@ some of these libraries as well, depending on what modm modules you use:
 
 ## Windows
 
-We will use [Anaconda](https://www.anaconda.com/) ([Miniconda](http://conda.pydata.org/miniconda.html) [Windows installation](https://docs.conda.io/en/latest/miniconda.html#windows-installers) is sufficient) to create a new Python 3 environment and install all
-necessary packages:
+We will use [Anaconda][] ([Miniconda Windows installation][miniconda] is
+sufficient) to create a new Python 3 environment and install all necessary
+packages:
 
     conda create --name modm python=3 pip
     activate modm
     conda install -c conda-forge git
-    pip install jinja2 scons future pyelftools lbuild
+    pip install jinja2 scons future pyelftools lbuild gdbgui
 
 For ARM development install the Windows 32-bit build of the [GNU Arm Embedded
 Toolchain][gcc-arm-toolchain]. For programming and debugging ARM Cortex-M
-devices install the pre-build [OpenOCD binaries](http://gnutoolchains.com/arm-eabi/openocd/).
+devices install the pre-build [OpenOCD binaries][openocd_binaries].
 You'll need to add both `/bin` paths to your `PATH` variable manually.
 
 !!! warning "For non-English speakers"
-	For now project and build paths containing non-ASCII characters are not parsed correctly.
+	For now project and build paths containing non-ASCII characters are not
+	parsed correctly.
+
+!!! warning "Windows paths"
+	Windows created maximal incompatibility with it's `\` path separator.
+	Even though we try hard to not hardcode the path separator, there may still
+	be issues related to this. [Please open an issue][newissue] in that case.
 
 !!! info "Dear Windows users"
-	We don't regularly use Windows with modm, so we rely on YOU to keep these install instructions
-	working and up-to-date. Please [open a PR with improvements][contribute].
+	We don't regularly use Windows with modm, so we rely on YOU to keep these
+	install instructions working and up-to-date. Please [open a PR with
+	improvements][contribute].
 
 
 [contribute]: https://github.com/modm-io/modm/blob/develop/CONTRIBUTING.md
+[newissue]: https://github.com/modm-io/modm/issues/new
 [examples]: https://github.com/modm-io/modm/tree/develop/examples
 [gcc-arm-toolchain]: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm
 [openocd]: http://openocd.org
-[avr-gcc]: http://www.nongnu.org/avr-libc
-[avrdude]: http://www.nongnu.org/avrdude
+[avr-gcc]: https://www.nongnu.org/avr-libc
+[avrdude]: https://www.nongnu.org/avrdude
 [lbuild]: https://github.com/modm-io/lbuild
-[avr-gcc-latest]: https://github.com/salkinium/docker-avr-gcc/releases
+[scons]: https://www.scons.org
+[cmake]: https://www.cmake.org
+[anaconda]: https://www.anaconda.com
+[miniconda]: https://docs.conda.io/en/latest/miniconda.html#windows-installers
+[avr-gcc-latest]: https://github.com/modm-ext/docker-avr-gcc/releases
+[openocd_binaries]: https://gnutoolchains.com/arm-eabi/openocd
+[doxygen]: http://www.doxygen.nl
+[doxypress]: https://www.copperspice.com/documentation-doxypress.html
+[gdbgui]: https://www.gdbgui.com

docs/src/reference/documentation.md

@@ -83,7 +83,7 @@ The generated Doxypress/Doxygen documentation contains the original module docum
 lbuild options to changes in the generated source code.
 
 
-### Online API documentation
+## Online API Docs
 
-API documentation is available at https://docs.modm.io/ for a large and representative
-number of targets with all modules enabled.
+API documentation is available at [docs.modm.io](https://docs.modm.io/) for a
+large and representative number of targets with all modules enabled.

tools/build_script_generator/cmake/module.md

@@ -41,19 +41,33 @@ Generates the CMake build folders and initializes the build system.
     If you forget to call this first, the build will fail with this error message:
 
     ```
-     $ make build-release
+     $ make build
     Error: build/cmake-build-release is not a directory
     make: *** [build-release] Error 1
     ```
 
 
-#### make build-release
-#### make build-debug
+#### make clean
+
+Removes the CMake build artifacts.
+
+
+#### make cleanall
+
+Removes the entire build folder. You must then first call `make cmake` before
+being able to build again.
+
+
+#### make build
+
+```
+make build profile={debug|release}
+```
 
 Compiles your application into an executable using the release or debug profile.
 
 ```
- $ make build-release
+ $ make build profile=release
 Scanning dependencies of target blink_cmake
 [  3%] Building C object CMakeFiles/blink_cmake.dir/modm/ext/cmsis/device/peripherals.c.o
 [  7%] Building CXX object CMakeFiles/blink_cmake.dir/modm/src/modm/architecture/driver/atomic/flag.cpp.o
@@ -69,16 +83,41 @@ Scanning dependencies of target blink_cmake
 ```
 
 
-#### make upload-release
-#### make upload-debug
+#### make size
+
+```
+make size profile={debug|release}
+```
+
+Displays the static Flash and RAM consumption of your target.
+
+Example for the Blue Pill target:
+
+```
+ $ make size
+
+Program:   1.4 KiB (2.2% used)
+(.build_id + .fastcode + .fastdata + .hardware_init + .rodata +
+ .table.copy.intern + .table.heap + .table.zero.intern + .text + .vector_rom)
+
+Data:      3.0 KiB (15.1% used) = 20 B static (0.1%) + 3072 B stack (15.0%)
+(.bss + .fastdata + .stack)
+
+Heap:     17.0 KiB (84.9% available)
+(.heap1)
+```
+
+
+#### make program
+
+```
+make program profile={debug|release} [port={serial-port}]
+```
 
 Writes the executable onto your target via AvrDude or OpenOCD.
-This is a convenience wrapper around the programming options and methods
-defined in the `modm:build` module.
-(\* *only AVR and ARM Cortex-M targets*)
 
 ```
- $ make upload-release
+ $ make program
 [100%] Built target blink_cmake
 [100%] Built target blink_cmake.bin
 [100%] Built target blink_cmake.hex
@@ -102,33 +141,64 @@ verified 1652 bytes in 0.104584s (15.426 KiB/s)
 shutdown command invoked
 ```
 
+#### make program-bmp
 
-#### make gdb
-#### make gdb-release
+```
+make program-bmp profile={debug|release} [port={serial-port}]
+```
 
-Launches GDB with the debug or release executable.
-This is just a convenience wrapper for the debug functionality defined in the
-`modm:build` module.
+Writes the executable onto your target via Black Magic Probe.
 (\* *only ARM Cortex-M targets*)
 
-**OpenOCD must already be running in the background**. Launch it by manually
-calling `make openocd` in another terminal.
 
+#### make debug
 
-#### make openocd
+```
+make debug profile={debug|release} ui={tui|web}
+```
 
-Starts OpenOCD with the modm specific configuration.
+Launches OpenOCD in the background, then launches GDB in foreground with the
+correct executable with text-based or [web-based gdbgui](gdbgui) UI. When GDB
+exits, it stops the OpenOCD process.
+(\* *only ARM Cortex-M targets*)
 
+To use gdbgui you must have it installed via `pip install gdbgui`.
 
-#### make clean
+!!! tip "Choose the correct profile"
+    When debugging, make sure to select the correct compilation profile. The
+    firmware and the executable given to GDB have to be the some or you'll see
+    GDB translate the program counter to the wrong code locations. When you
+    suspect a bug in your firmware, consider that it was most likely compiled
+    with the release profile, since that's the default. First try to
+    `make debug profile=release`, and if that doesn't help, compile and
+    `make program profile=debug` and try `make debug profile=debug` again.
 
-Removes the CMake build artifacts.
 
+#### make debug-coredump
 
-#### make cleanall
+```
+make debug-coredump profile={debug|release} ui={tui|web}
+```
 
-Removes the entire build folder. You must then first call `make cmake` before
-being able to build again.
+Launches GDB for post-mortem debugging with the using the data in the
+`coredump.txt` argument.
+(\* *only ARM Cortex-M targets*)
+
+See the `:platform:fault` module for details how to receive the coredump data.
+
+
+#### make log-itm
+
+```
+make log-itm fcpu={HCLK in Hz}
+```
+
+Configures OpenOCD in tracing mode to output ITM channel 0 on SWO pin and
+displays the serial output stream.
+
+See the `:platform:itm` module for details how to use the ITM as a logging
+output.
 
 
 [cmake]: http://cmake.org
+[gdbgui]: https://www.gdbgui.com

tools/build_script_generator/module.lb

@@ -10,16 +10,41 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 # -----------------------------------------------------------------------------
 
-import os
+import os, sys
+from pathlib import Path
 
 # import all common code
 with open(localpath("common.py")) as common:
     exec(common.read())
 
+class BuildModuleDocs:
+    def __init__(self):
+        self._content = None
+
+    def __str__(self):
+        if self._content is None:
+            self._content = Path(localpath("module.md")).read_text().strip()
+            tools = ["avrdude", "openocd", "bmp", "gdb", "size",
+                     "unittest", "log", "build_id", "bitmap"]
+
+            for tool in tools:
+                tpath = Path(repopath("tools/modm_tools/{}.py".format(tool)))
+                doc = None
+                if tpath.with_suffix(".md").exists():
+                    doc = tpath.with_suffix(".md").read_text()
+                elif tpath.exists():
+                    co = compile(tpath.read_bytes(), tpath, 'exec')
+                    if co.co_consts and isinstance(co.co_consts[0], str):
+                        doc = co.co_consts[0]
+                if doc is not None:
+                    self._content += "\n\n\n" + doc.strip()
+
+        return self._content
 
+# -----------------------------------------------------------------------------
 def init(module):
     module.name = ":build"
-    module.description = FileReader("module.md")
+    module.description = BuildModuleDocs()
 
 
 def prepare(module, options):