Migrate to MkDocs

roboticslab-uc3m/questions-and-answers#99

.github/workflows/gh-pages.yml

@@ -0,0 +1,26 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+    - mkdocs # FIXME
+    paths-ignore:
+    - README.md
+    - CONTRIBUTING.md
+    - CMakeLists.txt
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: fkirc/skip-duplicate-actions@v5
+      with:
+        cancel_others: 'true'
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # for the 'Last updated' timestamp
+    - name: Install requirements
+      run: pip install -r requirements.txt
+    - name: Build and deploy site
+      run: mkdocs gh-deploy --no-history

.gitignore

@@ -1,14 +1,15 @@
-# .gitignore
 ## Files we want to have locally, but do not want to push to remote
 
 ## Editor swap files
 *~
 *.swp
 *.orig
 
-## gitbook
-/node_modules/
-/_book/
+## CMake build system
+**/build*/
 
-# Miscellanea
+## mkdocs
+/site/
+
+# miscellanea
 /venv/

README.md

@@ -1,4 +1,4 @@
-[![roboticslab-uc3m logo](assets/roboticslab-banner-350px.png)](https://github.com/roboticslab-uc3m)
+[![roboticslab-uc3m logo](docs/assets/roboticslab-banner-350px.png)](https://github.com/roboticslab-uc3m)
 
 # Developer Manual
 
@@ -7,25 +7,31 @@ Developer Manual @ [roboticslab-uc3m](https://github.com/roboticslab-uc3m)
 Currently hosted at https://robots.uc3m.es/developer-manual/
 
 ## If you have any doubts or comments
+
 Please read the [Asking Questions](asking-questions.md) section, and once you've succeded with its [self-evaluation](asking-questions.md#self-evaluation-time) follow the recommendations by commenting publicly [HERE](https://github.com/roboticslab-uc3m/developer-manual/issues/new) if required
 
 ## How-To's
+
 * [How to serve on localhost](#how-to-serve-on-localhost)
 * [How to upload changes to GitHub](#how-to-upload-changes-to-github)
 
 ### How to serve on localhost
+
 It is useful to serve on `localhost` to modify the website and see changes locally.
 
-1. From the root of the project, run the following command (which is universal for all [Gitbook (legacy)](https://github.com/GitbookIO/gitbook)-based projects):
-```bash
-gitbook serve # command builds and serves
-```
+1. From the root of the project, run the following command:
 
-2. You can now browse the site at the default location: http://127.0.0.1:4000
+   ```bash
+   pip install -r requirements.txt
+   mkdocs serve
+   ```
+
+1. You can now browse the site at the default location: <http://127.0.0.1:8000>
 
 ### How to upload changes to GitHub
-This project is managed as any project on [GitHub](https://www.github.com). You may use [Git](https://git-scm.com) or even the GitHub web interface, both on which you can find many tutorials online. The following points are specific to the [Gitbook (legacy)](https://github.com/asrob-uc3m/actas/issues/148#issuecomment-449748350) mechanism used:
 
-1. Please **do not upload** the `_book/` folder. It is auto-generated locally, and the same should happen on the Gitbook (legacy) servers.
+This project is managed as any project on [GitHub](https://www.github.com). You may use [Git](https://git-scm.com) or even the GitHub web interface, both on which you can find many tutorials online. The following points are specific to the MkDocs mechanism used:
+
+1. Please **do not upload** the `site/` folder. It is auto-generated locally, and the same should happen on the MkDocs servers.
 
-2. It is safe to `git push` to any upstream branch, just remember that what is on `master` is what will be actually rendered as the website.
+1. It is safe to `git push` to any upstream branch, just remember that what is on `master` is what will be actually rendered as the website.

appendix/project-index.md → docs/appendix/project-index.md

@@ -85,4 +85,4 @@ Projects related to our research in [XGNITIVE](http://roboticslab.uc3m.es/roboti
 
 ## If you have any doubts or comments
 
-Please read the [Asking Questions](asking-questions.md) section, and once you've succeded with its [self-evaluation](asking-questions.md#self-evaluation-time) follow the recommendations by commenting publicly [HERE](https://github.com/roboticslab-uc3m/developer-manual/issues/new) if required
+Please read the [Asking Questions](../asking-questions.md) section, and once you've succeded with its [self-evaluation](../asking-questions.md#self-evaluation-time) follow the recommendations by commenting publicly [HERE](https://github.com/roboticslab-uc3m/developer-manual/issues/new) if required.

appendix/repository-index.md → docs/appendix/repository-index.md

@@ -22,12 +22,12 @@ List of repositories provided by [Robotics Lab](http://roboticslab.uc3m.es) of U
 - [vision](https://github.com/roboticslab-uc3m/vision) ([doxygen](https://robots.uc3m.es/vision/))
 - [yarp-devices](https://github.com/roboticslab-uc3m/yarp-devices) ([doxygen](https://robots.uc3m.es/yarp-devices/))
 - Simulation
-  - [openrave-tools](https://github.com/roboticslab-uc3m/openrave-tools)
-  - [openrave-yarp-plugins](https://github.com/roboticslab-uc3m/openrave-yarp-plugins) ([doxygen](https://robots.uc3m.es/openrave-yarp-plugins/))
-  - [gazebo-tools](https://github.com/roboticslab-uc3m/gazebo-tools)
-  - [coppeliasim-tools](https://github.com/roboticslab-uc3m/coppeliasim-tools)
-  - [webots-tools](https://github.com/roboticslab-uc3m/webots-tools)
-  - Also see models in each corresponding section of [Robots (individual)](#robots-individual)
+    - [openrave-tools](https://github.com/roboticslab-uc3m/openrave-tools)
+    - [openrave-yarp-plugins](https://github.com/roboticslab-uc3m/openrave-yarp-plugins) ([doxygen](https://robots.uc3m.es/openrave-yarp-plugins/))
+    - [gazebo-tools](https://github.com/roboticslab-uc3m/gazebo-tools)
+    - [coppeliasim-tools](https://github.com/roboticslab-uc3m/coppeliasim-tools)
+    - [webots-tools](https://github.com/roboticslab-uc3m/webots-tools)
+    - Also see models in each corresponding section of [Robots (individual)](#robots-individual)
 
 ## Robots (Individual)
 
@@ -39,7 +39,7 @@ Repositories related to our [AMOR](http://roboticslab.uc3m.es/roboticslab/robot/
 - [amor-configuration-files](https://github.com/roboticslab-uc3m/amor-configuration-files)
 - [amor-api](https://github.com/roboticslab-uc3m/amor-api) (private)
 - Simulation
-  - [amor-openrave-models](https://github.com/roboticslab-uc3m/amor-openrave-models)
+    - [amor-openrave-models](https://github.com/roboticslab-uc3m/amor-openrave-models)
 
 ### ASIBOT
 
@@ -49,7 +49,7 @@ Repositories related to our [ASIBOT](http://roboticslab.uc3m.es/roboticslab/robo
 - [asibot-configuration-files](https://github.com/roboticslab-uc3m/asibot-configuration-files)
 - [asibot-hmi](https://github.com/roboticslab-uc3m/asibot-hmi)
 - Simulation
-  - [asibot-openrave-models](https://github.com/roboticslab-uc3m/asibot-openrave-models)
+    - [asibot-openrave-models](https://github.com/roboticslab-uc3m/asibot-openrave-models)
 
 ### TEO
 
@@ -60,21 +60,28 @@ Repositories related to our [TEO](http://roboticslab.uc3m.es/roboticslab/robot/t
 - [teo-configuration-files](https://github.com/roboticslab-uc3m/teo-configuration-files)
 - [teo-hardware-issues](https://github.com/roboticslab-uc3m/teo-hardware-issues) (private)
 - [teo-ipos-backup](https://github.com/roboticslab-uc3m/teo-ipos-backup) (private)
+- [teo-electronics](https://github.com/roboticslab-uc3m/teo-electronics) (private)
 - Simulation
-  - [teo-blender-models](https://github.com/roboticslab-uc3m/teo-blender-models)
-  - [teo-bullet-models](https://github.com/roboticslab-uc3m/teo-bullet-models)
-  - [teo-coppeliasim-models](https://github.com/roboticslab-uc3m/teo-coppeliasim-models)
-  - [teo-gazebo-models](https://github.com/roboticslab-uc3m/teo-gazebo-models)
-  - [teo-openrave-models](https://github.com/roboticslab-uc3m/teo-openrave-models)
-  - [teo-webots-models](https://github.com/roboticslab-uc3m/teo-webots-models)
-  - [teo-simox-models](https://github.com/roboticslab-uc3m/teo-simox-models)
-  - [teo_robot](https://github.com/roboticslab-uc3m/teo_robot)
-  - [teo-ros-simulation](https://github.com/roboticslab-uc3m/teo-ros-simulation)
+    - [teo-blender-models](https://github.com/roboticslab-uc3m/teo-blender-models)
+    - [teo-bullet-models](https://github.com/roboticslab-uc3m/teo-bullet-models)
+    - [teo-coppeliasim-models](https://github.com/roboticslab-uc3m/teo-coppeliasim-models)
+    - [teo-gazebo-models](https://github.com/roboticslab-uc3m/teo-gazebo-models)
+    - [teo-openrave-models](https://github.com/roboticslab-uc3m/teo-openrave-models)
+    - [teo-webots-models](https://github.com/roboticslab-uc3m/teo-webots-models)
+    - [teo-simox-models](https://github.com/roboticslab-uc3m/teo-simox-models)
+    - [teo_robot](https://github.com/roboticslab-uc3m/teo_robot)
+    - [teo-ros-simulation](https://github.com/roboticslab-uc3m/teo-ros-simulation)
 - Demos
-  - [teo-self-presentation](https://github.com/roboticslab-uc3m/teo-self-presentation)
-  - [teo-demos-misc](https://github.com/roboticslab-uc3m/teo-demos-misc)
-  - [teo-follow-me](https://github.com/roboticslab-uc3m/teo-follow-me)
-  - [waiter](https://github.com/roboticslab-uc3m/waiter)
+    - [teo-self-presentation](https://github.com/roboticslab-uc3m/teo-self-presentation)
+    - [teo-demos-misc](https://github.com/roboticslab-uc3m/teo-demos-misc)
+    - [teo-follow-me](https://github.com/roboticslab-uc3m/teo-follow-me)
+    - [waiter](https://github.com/roboticslab-uc3m/waiter)
+- Firmware
+    - [cui-pic-firmware](https://github.com/roboticslab-uc3m/cui-pic-firmware)
+    - [lacquey-pic-firmware](https://github.com/roboticslab-uc3m/lacquey-pic-firmware) (legacy)
+    - [jr3-mbed-firmware](https://github.com/roboticslab-uc3m/jr3-mbed-firmware)
+    - [textiles-arduino-firmware](https://github.com/roboticslab-uc3m/textiles-arduino-firmware)
+    - [Dextra](https://github.com/roboticslab-uc3m/Dextra)
 
 ### TIAGo
 
@@ -168,4 +175,4 @@ We used to have some repositories at [https://apps-robots.uc3m.es/svn/\*](https:
 
 ## If you have any doubts or comments
 
-Please read the [Asking Questions](asking-questions.md) section, and once you've succeded with its [self-evaluation](asking-questions.md#self-evaluation-time) follow the recommendations by commenting publicly [HERE](https://github.com/roboticslab-uc3m/developer-manual/issues/new) if required
+Please read the [Asking Questions](../asking-questions.md) section, and once you've succeded with its [self-evaluation](../asking-questions.md#self-evaluation-time) follow the recommendations by commenting publicly [HERE](https://github.com/roboticslab-uc3m/developer-manual/issues/new) if required.

appendix/yarp-tricks.md → docs/appendix/yarp-tricks.md

@@ -180,7 +180,7 @@ Some specific to [CanBusControlBoard](https://github.com/roboticslab-uc3m/yarp-d
 
 ### remote_grabber
 
-- https://github.com/roboticslab-uc3m/yarp-devices/tree/f4d5f67d31703e41cea721080fd16d6777e67799/libraries/YarpPlugins/AravisGigE#camera-parameters-control
+- <https://github.com/roboticslab-uc3m/yarp-devices/tree/f4d5f67d31703e41cea721080fd16d6777e67799/libraries/YarpPlugins/AravisGigE#camera-parameters-control>
 
 ## Yarp streaming commands
 
@@ -201,7 +201,7 @@ Example: `yarp write ... /teo/leftHand/command:i`.
 ## Edit .ini config files in Calc (Excel)
 
 Click `Separated by space` and `Merge delimiters`.
-```bash
+```
 #!/bin/sh
 openoffice.org -calc launchManipulation.ini
 # libreoffice -calc launchManipulation.ini

asking-questions.md → docs/asking-questions.md

@@ -25,10 +25,11 @@ Please open a GitHub Issue following [THESE GUIDELINES ("Opening a GitHub Issue"
 ## I really don't like GitHub Issues, why can't I just bug somebody who knows the answer?
 
 There are several reasons to prefer GitHub Issues rather than asking in person or private messaging:
+
 * Answers are left for future people with doubts, and even the *you from the future* can run into the same issue after some time and then find the solution online!
 * Developers can have more time to perform research and/or create new cool applications, maybe even that coffee-making or pizza-delivery robot you've been waiting for, yay!
 * GitHub Issues have proved many times to be an efficient mechanism to receive answers from very unexpected contributors, which have provided many answers, new ideas, and worthy viewpoints!!
 
 ## Self evaluation time!
 
-https://goo.gl/forms/s9RNrCZqVUAaausf1
+<https://goo.gl/forms/s9RNrCZqVUAaausf1>