Refactor documentation and remove legacy Wolfgang documents

src/bitbots_misc/bitbots_docs/docs/conf.py

@@ -88,7 +88,7 @@ def count_files():
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

src/bitbots_misc/bitbots_docs/docs/index.rst

@@ -9,41 +9,48 @@ The main repository is `bitbots_main <https://github.com/bit-bots/bitbots_main>`
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-    :caption: Tutorials:
+    :caption: Getting Started:
 
-    manual/tutorials/*
+    manual/getting_started/setup
+    manual/getting_started/software_overview
+    manual/getting_started/simulation_testing
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-    :caption: Testing:
-
-    manual/testing/*
-
+    :caption: Physical Robot:
+
+    manual/physical_robot/robots
+    manual/physical_robot/setup_robot
+    manual/physical_robot/competition_wifi
+    manual/physical_robot/piplus_hardware
+    manual/physical_robot/starting_robot
+    manual/physical_robot/connecting
+    manual/physical_robot/testing_robot
+    manual/physical_robot/extrinsic_calibration
+    manual/physical_robot/hardware_checklist
+    manual/physical_robot/configure_launch
+    manual/physical_robot/test_robot_hardware
+    manual/physical_robot/lowlevel
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-    :caption: Software
-
-    manual/software/*
+    :caption: Development:
 
+    manual/development/development_guidelines
+    manual/development/how_to_document
+    manual/development/testing
+    manual/development/rl_models
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-    :caption: Electronics Wolfgang
-
-    manual/hardware/electronics/*
+    :caption: Glossary:
 
+    manual/glossary
 
-.. toctree::
-    :maxdepth: 1
-    :glob:
-    :caption: Mechanics Wolfgang
-
-    manual/hardware/mechanics/*
+.. todo::
+   Rework of the public documentation (see issue #1037): replace the plain link
+   to the default package directory index below with a curated list of all
+   packages that have non-empty documentation.
 
 `Package Documentations <https://docs.bit-bots.de/package/>`_
 

src/bitbots_misc/bitbots_docs/docs/manual/software/coding_style.rst → src/bitbots_misc/bitbots_docs/docs/manual/development/development_guidelines.rst

@@ -1,20 +1,40 @@
+Development Guidelines
+======================
+
+.. todo::
+   Rework of the public documentation (see issue #1037): flesh out the sections
+   below into full prose and link to the relevant tooling.
+
+How We Develop
+--------------
+
+- Create a branch named ``feature/*``, ``fix/*``, or ``docs/*``.
+- Always create a pull request for anything that may be merged. If it is not
+  finished yet, create a draft pull request.
+- Once it is ready, ask for review from the relevant authors and respond to and
+  fix those comments.
+- CI needs to pass.
+- If you do not have the capacity to make a pull request right now, open an
+  issue instead.
+- Add pull requests and issues to the project board.
+
 Coding Style
-============
+------------
 
 To maintain a consistent coding style throughout the codebase, we use automatic formatting tools.
 For this, we use `pre-commit <https://pre-commit.com/>`_ hooks that automatically format the code when a commit is made.
 Our configuration can be found in the ``.pre-commit-config.yaml`` file in the root of the repository.
 Continuous Integration (CI) also checks if the code is formatted correctly.
 
 Setting up pre-commit
----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
   pre-commit install
 
 Running pre-commit manually
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to run pre-commit manually on all files, you can use the following command:
 
@@ -23,7 +43,7 @@ If you want to run pre-commit manually on all files, you can use the following c
   pixi run format
 
 Git Commit conventions
-======================
+----------------------
 
 We also have some conventions about how we want to use git. They are as follows:
 

src/bitbots_misc/bitbots_docs/docs/manual/tutorials/Docs-How-To.rst → src/bitbots_misc/bitbots_docs/docs/manual/development/how_to_document.rst

@@ -16,6 +16,8 @@ The correct version of the extentions must be installed.
         pip3 install exhale --user
 
 
+.. _build_documentation:
+
 How to build the documentation
 ==============================
 

src/bitbots_misc/bitbots_docs/docs/manual/tutorials/rl_models.rst → src/bitbots_misc/bitbots_docs/docs/manual/development/rl_models.rst

@@ -2,6 +2,12 @@
 Reinforcement Learning of Policies and Deployment
 =================================================
 
+.. todo::
+   Rework of the public documentation (see issue #1037): this page lives in the
+   Development section. It is linked from
+   :doc:`../physical_robot/testing_robot` where the RL motion commands are
+   referenced.
+
 We use several reinforcement learning frameworks to train policies for our robots.
 After the models have been trained we export them as onnx files which describe the neural network structure and weights.
 We use the bitbots_rl_motion policy execution framework to deploy the models on our robots.

src/bitbots_misc/bitbots_docs/docs/manual/testing/testing.rst → src/bitbots_misc/bitbots_docs/docs/manual/development/testing.rst

@@ -2,6 +2,12 @@
 How to Test
 ===========
 
+.. todo::
+   Rework of the public documentation (see issue #1037): this general testing
+   page is not explicitly placed in the new structure. Confirm whether it belongs
+   under "Development" (as kept here) or should be merged with
+   :doc:`../getting_started/simulation_testing`.
+
 General Remarks
 ===============
 

src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst → src/bitbots_misc/bitbots_docs/docs/manual/getting_started/setup.rst

@@ -1,8 +1,18 @@
-Software installation guide
-===========================
+Setup
+=====
 
 In this tutorial, we will learn how to install all dependencies and build our software stack.
 
+.. todo::
+   Rework of the public documentation (see issue #1037):
+
+   - This page should have the same content as the repository ``README.md``; our
+     install instructions are small enough to fully fit here. Keep the two in
+     sync.
+   - Mention that Zenoh is required for almost all of our software to run.
+   - Mention that all commands need to be run from inside ``pixi shell`` or with
+     ``pixi run``.
+
 **TLDR**: single command setup
 ------------------------------
 
@@ -27,8 +37,6 @@ Manual steps with in depth explanation
 We mainly develop and test our software on Ubuntu so we recommend using Ubuntu for development as well.
 Due to the use of pixi other distributions as well as Mac OS might work as well, but might require some tweaks.
 
-Alternatively you can use a devcontainer :doc:`vscode-dev-container`, with a pre-configured environment and follow those instructions, as these docs do not apply to the devcontainer.
-
 **1. Install Pixi**
 
 We manage our development environment with `pixi <https://pixi.sh>`_, which makes setting up and using our software stack much easier.

src/bitbots_misc/bitbots_docs/docs/manual/testing/sim_test.rst → src/bitbots_misc/bitbots_docs/docs/manual/getting_started/simulation_testing.rst

@@ -6,7 +6,7 @@ Test Motion
 
 .. code-block:: bash
 
-    ros2 launch bitbots_mujoco_sim simulation.launch
+    ros2 launch bitbots_mujoco_sim simulator.launch
     ros2 launch bitbots_bringup motion_standalone.launch sim:=true
 
 To control walking of the robot, teleop needs to be startet as well:

src/bitbots_misc/bitbots_docs/docs/manual/tutorials/launch_files.rst → src/bitbots_misc/bitbots_docs/docs/manual/getting_started/software_overview.rst

@@ -1,6 +1,17 @@
-==============
-Launch Scripts
-==============
+========================
+Global Software Overview
+========================
+
+.. todo::
+   Rework of the public documentation (see issue #1037): this page should give a
+   global overview of our software. In addition to the bringup launch scripts
+   below, add:
+
+   - A high level data flow diagram of the software stack.
+   - A list of all bitbots packages with a short description, grouped by topic.
+
+Bringup Launch Scripts
+======================
 
 Listed below are the most important launch files.
 You can display the arguments of the launch files in the terminal by using the command

src/bitbots_misc/bitbots_docs/docs/manual/glossary.rst

@@ -0,0 +1,13 @@
+Glossary
+========
+
+.. todo::
+   Rework of the public documentation (see issue #1037): collect the recurring
+   Bit-Bots and RoboCup terms used throughout this documentation and define them
+   here, using the reStructuredText ``glossary`` directive so that ``:term:``
+   references can link to the definitions.
+
+.. glossary::
+
+   PiPlus
+      The current Bit-Bots humanoid robot platform.