From 5c37363e3d541fd1827c195679d8507ffd986920 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20=C5=81ukawski?= Date: Tue, 14 Nov 2023 18:11:46 +0100 Subject: [PATCH] Migrate to MkDocs https://github.com/roboticslab-uc3m/questions-and-answers/issues/99 --- .github/workflows/gh-pages.yml | 26 ++ .github/workflows/gitbook.yml | 29 --- .gitignore | 11 +- README.md | 24 +- SUMMARY.md | 16 -- book.json | 13 - dev-aliases.yaml => dev-aliases.yml | 0 .../appendix}/additional-links.md | 0 appendix/README.md => docs/appendix/index.md | 0 {appendix => docs/appendix}/project-index.md | 2 +- .../appendix}/repository-index.md | 51 ++-- {appendix => docs/appendix}/yarp-tricks.md | 4 +- .../asking-questions.md | 3 +- docs/assets/favicon.ico | Bin 0 -> 15086 bytes .../assets}/roboticslab-banner-350px.png | Bin docs/assets/roboticslab.svg | 235 ++++++++++++++++++ contributors.md => docs/contributors.md | 0 documenting.md => docs/documenting.md | 2 +- .../frequently-asked-questions.md | 51 ++-- github.md => docs/github.md | 15 +- gitbook-cover.md => docs/index.md | 5 +- introduction.md => docs/introduction.md | 9 +- programming.md => docs/programming/index.md | 28 +-- .../programming/programming-with-yarp.md | 3 +- mkdocs.yml | 82 ++++++ requirements.txt | 4 + scripts/update_contributors.py | 4 +- styles/website.css | 8 - 28 files changed, 464 insertions(+), 161 deletions(-) create mode 100644 .github/workflows/gh-pages.yml delete mode 100644 .github/workflows/gitbook.yml delete mode 100644 SUMMARY.md delete mode 100644 book.json rename dev-aliases.yaml => dev-aliases.yml (100%) rename {appendix => docs/appendix}/additional-links.md (100%) rename appendix/README.md => docs/appendix/index.md (100%) rename {appendix => docs/appendix}/project-index.md (93%) rename {appendix => docs/appendix}/repository-index.md (74%) rename {appendix => docs/appendix}/yarp-tricks.md (96%) rename asking-questions.md => docs/asking-questions.md (98%) create mode 100644 docs/assets/favicon.ico rename {assets => docs/assets}/roboticslab-banner-350px.png (100%) create mode 100644 docs/assets/roboticslab.svg rename contributors.md => docs/contributors.md (100%) rename documenting.md => docs/documenting.md (94%) rename frequently-asked-questions.md => docs/frequently-asked-questions.md (86%) rename github.md => docs/github.md (91%) rename gitbook-cover.md => docs/index.md (81%) rename introduction.md => docs/introduction.md (85%) rename programming.md => docs/programming/index.md (78%) rename programming-with-yarp.md => docs/programming/programming-with-yarp.md (98%) create mode 100644 mkdocs.yml create mode 100644 requirements.txt delete mode 100644 styles/website.css diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..ad07dd3 --- /dev/null +++ b/.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 diff --git a/.github/workflows/gitbook.yml b/.github/workflows/gitbook.yml deleted file mode 100644 index 5c7553f..0000000 --- a/.github/workflows/gitbook.yml +++ /dev/null @@ -1,29 +0,0 @@ -name: GitBook - -on: - push: - branches: - - master - paths-ignore: - - README.md - - CONTRIBUTING.md - - CMakeLists.txt - workflow_dispatch: - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: fkirc/skip-duplicate-actions@master - with: - cancel_others: 'true' - - uses: actions/checkout@v2 - - name: Run GitBook - run: | - docker run --rm -v $GITHUB_WORKSPACE:/gitbook ghcr.io/roboticslab-uc3m/gitbook:latest gitbook install - docker run --rm -v $GITHUB_WORKSPACE:/gitbook ghcr.io/roboticslab-uc3m/gitbook:latest gitbook build - - uses: crazy-max/ghaction-github-pages@v2 - with: - build_dir: _book - env: - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.gitignore b/.gitignore index 798ca6a..7657e90 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ -# .gitignore ## Files we want to have locally, but do not want to push to remote ## Editor swap files @@ -6,9 +5,11 @@ *.swp *.orig -## gitbook -/node_modules/ -/_book/ +## CMake build system +**/build*/ -# Miscellanea +## mkdocs +/site/ + +# miscellanea /venv/ diff --git a/README.md b/README.md index ee826d7..63c6198 100644 --- a/README.md +++ b/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: ### 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. diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100644 index 1809f49..0000000 --- a/SUMMARY.md +++ /dev/null @@ -1,16 +0,0 @@ -# Summary - -* [Developer Manual](gitbook-cover.md) -* [Introduction](introduction.md) -* [Asking Questions](asking-questions.md) -* [Documenting](documenting.md) -* [GitHub](github.md) -* [Programming](programming.md) - * [Programming with YARP](programming-with-yarp.md) -* [Frequently Asked Questions (FAQ)](frequently-asked-questions.md) -* [Appendices](appendix/README.md) - * [Repository Index](appendix/repository-index.md) - * [Project Index](appendix/project-index.md) - * [YARP Tricks](appendix/yarp-tricks.md) - * [Additional Links](appendix/additional-links.md) -* [Contributors](contributors.md) diff --git a/book.json b/book.json deleted file mode 100644 index a178ffd..0000000 --- a/book.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "structure": { - "readme": "gitbook-cover.md" - }, - "plugins": "page-toc", - "pluginsConfig": { - "page-toc": { - "selector": ".markdown-section h2, .markdown-section h3, .markdown-section h4", - "position": "before-first", - "showByDefault": true - } - } -} diff --git a/dev-aliases.yaml b/dev-aliases.yml similarity index 100% rename from dev-aliases.yaml rename to dev-aliases.yml diff --git a/appendix/additional-links.md b/docs/appendix/additional-links.md similarity index 100% rename from appendix/additional-links.md rename to docs/appendix/additional-links.md diff --git a/appendix/README.md b/docs/appendix/index.md similarity index 100% rename from appendix/README.md rename to docs/appendix/index.md diff --git a/appendix/project-index.md b/docs/appendix/project-index.md similarity index 93% rename from appendix/project-index.md rename to docs/appendix/project-index.md index 2c19509..11e76c5 100644 --- a/appendix/project-index.md +++ b/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. diff --git a/appendix/repository-index.md b/docs/appendix/repository-index.md similarity index 74% rename from appendix/repository-index.md rename to docs/appendix/repository-index.md index 82b1e67..a578d78 100644 --- a/appendix/repository-index.md +++ b/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. diff --git a/appendix/yarp-tricks.md b/docs/appendix/yarp-tricks.md similarity index 96% rename from appendix/yarp-tricks.md rename to docs/appendix/yarp-tricks.md index a6f5402..167e5d1 100644 --- a/appendix/yarp-tricks.md +++ b/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 +- ## 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 diff --git a/asking-questions.md b/docs/asking-questions.md similarity index 98% rename from asking-questions.md rename to docs/asking-questions.md index 5601534..85b2337 100644 --- a/asking-questions.md +++ b/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 + diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..5be713ae5e3c40c0f62819579f474c06a82f8e4d GIT binary patch literal 15086 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 + + +image/svg+xml \ No newline at end of file diff --git a/contributors.md b/docs/contributors.md similarity index 100% rename from contributors.md rename to docs/contributors.md diff --git a/documenting.md b/docs/documenting.md similarity index 94% rename from documenting.md rename to docs/documenting.md index 9ffa0ce..8eadd27 100644 --- a/documenting.md +++ b/docs/documenting.md @@ -7,4 +7,4 @@ ## 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. diff --git a/frequently-asked-questions.md b/docs/frequently-asked-questions.md similarity index 86% rename from frequently-asked-questions.md rename to docs/frequently-asked-questions.md index 3808a02..6e55e8b 100644 --- a/frequently-asked-questions.md +++ b/docs/frequently-asked-questions.md @@ -9,8 +9,8 @@ - Please make sure you carefully read and understood the dedicated section at: [how do I install programs on Linux? (Spanish)](https://asrob.uc3m.es/tutoriales/software/linux/introduction.html#¿cómo-instalo-programas-en-linux) - Each of our repositories usually contains instructions for installing, e.g. the initial `README.md` of links to its [doc/vision-install.md](https://github.com/roboticslab-uc3m/vision/blob/master/doc/vision-install.md) documentation file. - - Note 1: Don't know what a repository is? Please read: [Control de versiones (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/index.html) - - Note 2: This manual contains an index of our repositories: [HERE](appendix/repository-index.md) + - Note 1: Don't know what a repository is? Please read: [Control de versiones (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/index.html) + - Note 2: This manual contains an index of our repositories: [HERE](appendix/repository-index.md) - For instructions on installing 3rd party software, please see a special repository we maintain: ## I see a lot of commands for installation but do not understand anything. What do they mean? @@ -20,8 +20,8 @@ ## I've heard lots of stuff about Git and GitHub. What do they mean? - Please read: - - [Git y GitHub (Spanish)](https://david-estevez.gitbooks.io/the-git-the-bad-and-the-ugly/content/es/control-de-versiones.html) - - [Control de versiones - Git (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/git.html) + - [Git y GitHub (Spanish)](https://david-estevez.gitbooks.io/the-git-the-bad-and-the-ugly/content/es/control-de-versiones.html) + - [Control de versiones - Git (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/git.html) ## How should I program stuff? @@ -41,19 +41,20 @@ Once you have publishing services running (robot joint/cartesian state, sensors 1. To record full trajectories (data stream of a certain YARP port) at a given sample rate, use [yarpdatadumper](http://www.yarp.it/yarpdatadumper.html). To record from several YARP ports, [yarpdatadumperAppGenerator](http://www.yarp.it/yarpdatadumperAppGenerator.html) can be used to generate a [yarpmanager](http://www.yarp.it/yarpmanager.html) app of [yarpdatadumper](http://www.yarp.it/yarpdatadumper.html) components. - An example of recording a left arm trayectory of TEO: - * Terminal 1: - ``` - launchManipulation # Part of teoBase - ``` - * Terminal 2: - ```bash - yarpdatadumper --name /leftArm # the data.log and data.log files will be saved in a new `leftArm` directory - ``` - * Terminal 3: - ```bash - yarp connect /teo/leftArm/state:o /leftArm - ``` +An example of recording a left arm trayectory of TEO: + +* Terminal 1: +``` +launchManipulation # Part of teoBase +``` +* Terminal 2: +``` +yarpdatadumper --name /leftArm # the data.log and data.log files will be saved in a new `leftArm` directory +``` +* Terminal 3: +``` +yarp connect /teo/leftArm/state:o /leftArm +``` ## How can I play back data recorded for Programming by Demonstration (PbD) a.k.a. Learning from Demonstration (LfD)? @@ -68,10 +69,12 @@ Note: There are several alternatives to these approaches, but these are kind of ## How does the iPos PT Mode work? `PT Mode` performs at a fixed rate at driver level. This is great, because it's real-time right next to the motor, so network latencies will not affect performance of set of a pre-defined joint-space targets (positions). Not justifying how it's implemented, but providing the reason why they actually did it as it is. Naïve options: + 1. First receive (e.g. via CAN-bus) all the trajectory, then execute each target at the exact time given the fixed period. The issue with this is: how much memory should we reserve for this? What happens if somebody wants to run a trajectory with thousands or millions of intermediate targets? 2. Receive the next target (e.g. via CAN-bus), execute it at exactly the planned time given the fixed period, repeat. The issue with this is: what happens if a target arrives late? None of these options is the implemented solution. The iPos implementation is an intermediate solution, essentially a [FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) memory with 8 buffer positions (would have to check the iPos manual for the specific correct value). So, you start filling it in, once it is initially full you start running, and then continue feeding it targets (e.g. via CAN-bus) at the rate established by the fixed period. + - If you feed it too slow, the buffer will empty before time and movement will stop. - If you feed it too fast, the buffer will get full (you'll see a `pt buffer full!` message in our [CanBusControlBoard](https://github.com/roboticslab-uc3m/yarp-devices/blob/e696c219fa9aa6203d008585123ea477d9b74454/libraries/YarpPlugins/CanBusControlBoard) implementation). @@ -82,11 +85,11 @@ In the current [CanBusControlBoard](https://github.com/roboticslab-uc3m/yarp-dev ## How can I change the RGB-D sensor resolution? We use the YARP `OpenNI2DeviceServer` device for this. In [teoBase.xml#L36](https://github.com/roboticslab-uc3m/teo-configuration-files/blob/89d6e279d13cfe47c444c709cd7a08e5de56382b/share/teoBase/scripts/teoBase.xml#L36) you can see an example instance: -```bash +``` yarpdev --device OpenNI2DeviceServer --depthVideoMode 4 --colorVideoMode 9 --noRGBMirror ``` If you want to know what values you can use for `--depthVideoMode` and `--colorVideoMode` instead (and the actual meaning of the current values), please launch: -```bash +``` yarpdev --device OpenNI2DeviceServer --printVideoModes ``` @@ -94,11 +97,11 @@ yarpdev --device OpenNI2DeviceServer --printVideoModes Most of this was done at https://github.com/roboticslab-uc3m/questions-and-answers/issues/2 -- https://github.com/roboticslab-uc3m/teo-body -> https://github.com/roboticslab-uc3m/yarp-devices -- https://github.com/roboticslab-uc3m/teo-head -> https://github.com/roboticslab-uc3m/vision and https://github.com/roboticslab-uc3m/speech -- https://github.com/roboticslab-uc3m/teo-main (old version) -> https://github.com/roboticslab-uc3m/kinematics-dynamics -- https://github.com/roboticslab-uc3m/best-practices -> https://github.com/roboticslab-uc3m/developer-manual -- https://github.com/roboticslab-uc3m/teo-software-manual -> https://github.com/roboticslab-uc3m/teo-developer-manual +- -> +- -> and +- -> +- -> +- -> ## I have read this page and related links, and I have doubts and/or comments. What should I do? diff --git a/github.md b/docs/github.md similarity index 91% rename from github.md rename to docs/github.md index 3c2f2af..f6f070c 100644 --- a/github.md +++ b/docs/github.md @@ -10,9 +10,9 @@ * If it is clearly specific to one repository, go to that repository. Examples: [yarp-devices](https://github.com/roboticslab-uc3m/yarp-devices/issues), [kinematics-dynamics](https://github.com/roboticslab-uc3m/kinematics-dynamics/issues), [vision](https://github.com/roboticslab-uc3m/vision/issues)... * If it is related to the installation of a dependency, go to [installation-guides](https://github.com/roboticslab-uc3m/installation-guides/issues) * If it is extremely generic but refers to a specific research project, go to the research project's main repository. Examples: [alma](https://github.com/roboticslab-uc3m/alma/issues), [roboasset](https://github.com/roboticslab-uc3m/roboasset/issues)... - * Note that research projects have more specific repositories, see the [Project Index](appendix/project-index.md). + * Note that research projects have more specific repositories, see the [Project Index](appendix/project-index.md). * If it is extremely generic but refers to a specific robot, go to the robot's main repository. Examples: [teo-main](https://github.com/roboticslab-uc3m/teo-main/issues), [asibot-main](https://github.com/roboticslab-uc3m/asibot-main/issues)... - * Note that robots have more specific repositories, see the [Repository Index (Robots section)](appendix/repository-index.md#robots-individual); e.g. TEO has its own private [teo-hardware-issues](https://github.com/roboticslab-uc3m/teo-hardware-issues/issues) repository where you can also open an issue on any specific TEO hardware issue. + * Note that robots have more specific repositories, see the [Repository Index (Robots section)](appendix/repository-index.md#robots-individual); e.g. TEO has its own private [teo-hardware-issues](https://github.com/roboticslab-uc3m/teo-hardware-issues/issues) repository where you can also open an issue on any specific TEO hardware issue. * If it extremely generic and fits nowhere else, go to: [questions-and-answers](https://github.com/roboticslab-uc3m/questions-and-answers) 1. Fix the objective/scope of the Issue to be as "achievable" as possible. If the task at hand seems too broad or prone to become labeled `epic`, open several Issues where each can be acomplished in less than 1-2 weeks. 1. Click on `Issues`, then on `New Issue` @@ -27,6 +27,7 @@ 1. If you have permissions, add the Issue to closest related `Project(s)`. Troubleshooting: + - In certain repositories (none of the https://github.com/roboticslab-uc3m GitHub organization), you have to be part of the specific GitHub organization to be able to put an Issue. Please contact the specific GitHub organization owners if given the case. ### Closing a GitHub Issue @@ -35,21 +36,20 @@ Please cite the hash of the commit that closes the GitHub Issue (ideally, the ha ### GitHub Issue Labels -We are attempting to unify GitHub labels, spawned from [questions-and-answers#76](https://github.com/roboticslab-uc3m/questions-and-answers/issues/76) +We are attempting to unify GitHub labels, spawned from [questions-and-answers#76](https://github.com/roboticslab-uc3m/questions-and-answers/issues/76). + - Existing repos: use https://github.com/destan/github-label-manager or similar to copy from [teo-main](https://github.com/roboticslab-uc3m/teo-main/labels). - New repos: new repos will inherit labels defined at https://github.com/organizations/roboticslab-uc3m/settings/labels ## git commit (and push) -We have seen in [Main Developer Tools](main-developer-tools.md) that GitHub is an important part of our workflow. Now let's see when and how to use it. - ### When should I commit to GitHub? Essentially, always. Whatever you are doing, as insignificant as it may seem, please upload the files to GitHub. Read on for the details. ### To which GitHub repository should I commit? -Please use one of our repositories: [Repository Index](repository-index.md). +Please use one of our repositories: [Repository Index](appendix/repository-index.md). ### To which repository branch should I commit? @@ -58,6 +58,7 @@ Please upload your work to a new branch, branching out from `master`. This git w ### Which files should I commit to the branch? We commented above to commit absolutely everything, as insignificant as it may seem. There are a few exceptions, please AVOID uploading (all equally important): + * Files that can be generated via other files (executables, `.pdf`...): instead, document how to generate these files (steps for compiling/installing, `pdflatex`...) * Compressed files (e.g. `.zip`): please upload each individual file (which can be done within the same commit) * Big files (e.g. bibliography `.pdf`, videos...): think about more appropiate mechanisms (Mendeley, Google Drive...) and instead provide links in descriptions @@ -105,4 +106,4 @@ Read more at [questions-and-answers#74](https://github.com/roboticslab-uc3m/ques ## 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. diff --git a/gitbook-cover.md b/docs/index.md similarity index 81% rename from gitbook-cover.md rename to docs/index.md index f4c6b57..be411de 100644 --- a/gitbook-cover.md +++ b/docs/index.md @@ -4,11 +4,12 @@ Developer Manual @ [roboticslab-uc3m](https://github.com/roboticslab-uc3m) -Click on the option you want, or use the arrows to move sequentially +Click on the option you want, or use the `P` and `N` keys to navigate through the sections (Previous, Next). ## Additional notes The content of this documentation is generated from files hosted on [GitHub](https://github.com/roboticslab-uc3m/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 + +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. diff --git a/introduction.md b/docs/introduction.md similarity index 85% rename from introduction.md rename to docs/introduction.md index 3cc9e51..d18d697 100644 --- a/introduction.md +++ b/docs/introduction.md @@ -9,8 +9,8 @@ - Please make sure you carefully read and understood the dedicated section at: [how do I install programs on Linux? (Spanish)](https://asrob.uc3m.es/tutoriales/software/linux/introduction.html#¿cómo-instalo-programas-en-linux) - Each of our repositories usually contains instructions for installing, e.g. the initial `README.md` of links to its [doc/vision-install.md](https://github.com/roboticslab-uc3m/vision/blob/master/doc/vision-install.md) documentation file. - - Note 1: Don't know what a repository is? Please read: [Control de versiones (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/index.html) - - Note 2: This manual contains an index of our repositories: [HERE](appendix/repository-index.md) + - Note 1: Don't know what a repository is? Please read: [Control de versiones (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/index.html) + - Note 2: This manual contains an index of our repositories: [HERE](appendix/repository-index.md) - For instructions on installing 3rd party software, please see a special repository we maintain: ## I see a lot of commands for installation but do not understand anything. What do they mean? @@ -20,8 +20,8 @@ ## I've heard lots of stuff about Git and GitHub. What do they mean? - Please read: - - [Git y GitHub (Spanish)](https://david-estevez.gitbooks.io/the-git-the-bad-and-the-ugly/content/es/control-de-versiones.html) - - [Control de versiones - Git (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/git.html) + - [Git y GitHub (Spanish)](https://david-estevez.gitbooks.io/the-git-the-bad-and-the-ugly/content/es/control-de-versiones.html) + - [Control de versiones - Git (Spanish)](https://asrob.uc3m.es/tutoriales/software/version-control/git.html) ## How should I program stuff? @@ -34,5 +34,6 @@ ## I have read this page and related links, and I have doubts and/or comments. What should I do? Please follow these steps: + 1. Read the [Asking Questions](asking-questions.md) section as many as times as required to succeded with its [self-evaluation](asking-questions.md#self-evaluation-time). 2. Follow its recommendations, which you will know because you have succeded in its [self-evaluation](asking-questions.md#self-evaluation-time). ^^ diff --git a/programming.md b/docs/programming/index.md similarity index 78% rename from programming.md rename to docs/programming/index.md index 556f69c..ed50db9 100644 --- a/programming.md +++ b/docs/programming/index.md @@ -13,7 +13,7 @@ ## General Programming * In case of trouble during installation of dependencies or additional software, take a look first at our dedicated repository: [installation-guides](https://github.com/roboticslab-uc3m/installation-guides) ([gitbook](https://robots.uc3m.es/installation-guides/)). -* If incorporating a new dependency or additional software, first take a look at our dedicated repository: [installation-guides](https://github.com/roboticslab-uc3m/installation-guides) ([gitbook](https://robots.uc3m.es/installation-guides/)). If it's not there, consider if it's a good option using the following recommended (but not mandatory) criteria: lightweight, flexible, multiplatform. If so, add it there, then link it to your project ([example](5182f9f475e229acea4cca1130be57489fd6b0f7)). +* If incorporating a new dependency or additional software, first take a look at our dedicated repository: [installation-guides](https://github.com/roboticslab-uc3m/installation-guides) ([gitbook](https://robots.uc3m.es/installation-guides/)). If it's not there, consider if it's a good option using the following recommended (but not mandatory) criteria: lightweight, flexible, multiplatform. If so, add it there, then link it to your project. * Indent your code as if everything were Python. [astyle](http://astyle.sourceforge.net/) can handle this quite automatically for you \(use with caution\). * Any `toDo`, `fixMe`, etc. inlined in code must be associated to an _open issue_ \(with bidirectional reference\). * [Headers, config files and CLI parameters](https://github.com/roboticslab-uc3m/asibot-main/blob/master/doc/asibot-post-install.md#changing-parameters). @@ -27,9 +27,9 @@ * [Tutorial (Spanish)](https://asrob.uc3m.es/tutoriales/software/programming/cmake.html) * Naming conventions: - * *SCREAMING\_SNAKE\_CASE* for the project name, files and configuration variables: `TEO_MAIN`, `TEO_MAINConfig.cmake.in`, `TEO_MAIN_INCLUDE_DIRS`. - * *kebab-case* for installed YARP context directories as set by `yarp_configure_external_installation()`: `teo-main`, `asibot-openrave-models`. - * Use the `ROBOTICSLAB_` (or `roboticslab-`) prefix whenever the uniqueness of the chosen name for the project could be easily compromised (keep in mind you'll want to invoke `find_package()`): `ROBOTICSLAB_YARP_DEVICES`, `ROBOTICSLAB_KINEMATICS_DYNAMICS_INCLUDE_DIRS`, `roboticslab-vision`. + * *SCREAMING\_SNAKE\_CASE* for the project name, files and configuration variables: `TEO_MAIN`, `TEO_MAINConfig.cmake.in`, `TEO_MAIN_INCLUDE_DIRS`. + * *kebab-case* for installed YARP context directories as set by `yarp_configure_external_installation()`: `teo-main`, `asibot-openrave-models`. + * Use the `ROBOTICSLAB_` (or `roboticslab-`) prefix whenever the uniqueness of the chosen name for the project could be easily compromised (keep in mind you'll want to invoke `find_package()`): `ROBOTICSLAB_YARP_DEVICES`, `ROBOTICSLAB_KINEMATICS_DYNAMICS_INCLUDE_DIRS`, `roboticslab-vision`. ## Programming in C/C++ @@ -45,18 +45,18 @@ * Keep a minimalistic `main()` by implementing your program as an OOP class, see comments on `RFModule` in best practices in [Programming with YARP](programming-with-yarp.md). * Create and maintain unit tests for each class. We are currently using **gtest**, see [kinematics-dynamics/tests/testKdlSolver](https://github.com/roboticslab-uc3m/kinematics-dynamics/tree/master/tests/testKdlSolver.cpp), which is then integrated with Travis CI. * It is recommended to mark a function as DEPRECATED for a month before eliminating it from an API. DEPRECATED macros can be generated via CMake as done [here](https://github.com/roboticslab-uc3m/kinematics-dynamics/blob/21f2dde2a38f1d0c1c93703d3619e34c14c3bfcd/CMakeLists.txt#L110-L118), then used within code as [here](https://github.com/roboticslab-uc3m/kinematics-dynamics/blob/21f2dde2a38f1d0c1c93703d3619e34c14c3bfcd/libraries/TeoYarp/ICartesianSolver.h#L29-L33). The full procedure, as described at [QA #21](https://github.com/roboticslab-uc3m/QA/issues/21), should be: - 1. Open a [GitHub Issue](github.md#github-issues) wherever the offending function is located. - 1. Label it as `announcement`. - 1. Use the search bar to localize any call to said function across roboticslab-uc3m and list all affected repos. - 1. If necessary, elaborate a removal plan and detail any steps that need to be taken to perform a seamless migration to the new API. - 1. Ping the corresponding team or whoever could need more action on their end. - 1. Proceed gradually and, finally, kill the function. + 1. Open a [GitHub Issue](github.md#github-issues) wherever the offending function is located. + 1. Label it as `announcement`. + 1. Use the search bar to localize any call to said function across roboticslab-uc3m and list all affected repos. + 1. If necessary, elaborate a removal plan and detail any steps that need to be taken to perform a seamless migration to the new API. + 1. Ping the corresponding team or whoever could need more action on their end. + 1. Proceed gradually and, finally, kill the function. * Always initialize class members, either in the class constructor or in any initialization method (e.g. your implementation of `DeviceDriver::open` when creating custom _YARP devices_) before doing the actual work. * More links to best practices: - * https://github.com/google/eng-practices - * https://google.github.io/styleguide/cppguide.html - * https://www.perforce.com/resources/qac/high-integrity-cpp-coding-standard + * + * + * ## 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. diff --git a/programming-with-yarp.md b/docs/programming/programming-with-yarp.md similarity index 98% rename from programming-with-yarp.md rename to docs/programming/programming-with-yarp.md index 145e51c..ffabae5 100644 --- a/programming-with-yarp.md +++ b/docs/programming/programming-with-yarp.md @@ -8,6 +8,7 @@ ### Regarding `close()` If there exists a `close` method that needs to release unmanaged resources (dynamically allocated memory) or terminate stuff in an ordered manner (if using `PolyDriver` class members, e.g. `close` device A before device B), always define a class destructor that calls `close`, be it a `DeviceDriver` or an `RFModule` derived class. Also, make sure nothing bad happens if this `close` method is called several times (i.e. set dangling pointers to `nullptr`). Why is that: + - `PolyDriver::open` may fail to initialize a subdevice, but it does not call the subdevice's `close` method; instead, it is immediately destructed via delete ([ref](https://github.com/robotology/yarp/blob/b3dff81c3739112b8f65cfd808f129bcbf4e7aa5/src/libYARP_dev/src/yarp/dev/PolyDriver.cpp#L308)). - If `RFModule::configure` returns false, as explained in the above comments, `close` will never be called, hence we also want to use a destructor here. - `PolyDriver::close` will never close a wrapped device twice, but callers of `RFModule` can do that inadvertently because of the previous point: once after a successful `RFModule::configure` and a `CTRL+C` signal (it just stops execution flow and calls close before leaving `runModule`), and one more time on class destruction. @@ -21,4 +22,4 @@ If there exists a `close` method that needs to release unmanaged resources (dyna ## 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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8eeaff4 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,82 @@ +site_name: Developer Manual + +repo_name: roboticslab-uc3m/developer-manual +repo_url: https://github.com/roboticslab-uc3m/developer-manual +edit_uri: blob/master/docs/ + +theme: + name: material + language: en + logo: assets/roboticslab.svg + favicon: assets/favicon.ico + features: + - content.action.edit + - content.action.view + - navigation.footer + - navigation.indexes + - navigation.sections + - navigation.top + - navigation.tracking + - search.highlight + - search.suggest + icon: + repo: fontawesome/brands/github + palette: + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: light-blue + accent: light-blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: light-blue + accent: light-blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + +extra: + social: + - icon: material/web + link: http://roboticslab.uc3m.es/ + - icon: fontawesome/brands/github + link: https://github.com/roboticslab-uc3m + - icon: fontawesome/brands/x-twitter + link: https://twitter.com/uc3mRoboticsLab + - icon: fontawesome/brands/youtube + link: https://www.youtube.com/@RoboticsLabUC3M + +exclude_docs: | + fig/README.md + fig/editable/README.md + +nav: +- index.md +- introduction.md +- asking-questions.md +- documenting.md +- GitHub: github.md +- Programming: + - programming/index.md + - Programming with YARP: programming/programming-with-yarp.md +- Frequently Asked Questions (FAQ): frequently-asked-questions.md +- Appendices: + - appendix/index.md + - Repository Index: appendix/repository-index.md + - Project Index: appendix/project-index.md + - YARP Tricks: appendix/yarp-tricks.md + - Additional Links: appendix/additional-links.md +- contributors.md + +use_directory_urls: false + +markdown_extensions: + - toc: + permalink: '#' + +plugins: + - search + - open-in-new-tab + - git-revision-date-localized diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..56e455d --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +mkdocs +mkdocs-material +mkdocs-open-in-new-tab +mkdocs-git-revision-date-localized-plugin diff --git a/scripts/update_contributors.py b/scripts/update_contributors.py index c12e0fd..d13a476 100644 --- a/scripts/update_contributors.py +++ b/scripts/update_contributors.py @@ -9,8 +9,8 @@ from github import Github, Auth from github.GithubException import IncompletableObject -ALIASES_FILE = 'dev-aliases.yaml' -OUT_FILE = 'contributors.md' +ALIASES_FILE = 'dev-aliases.yml' +OUT_FILE = 'docs/contributors.md' ORG_NAME = 'roboticslab-uc3m' with open(ALIASES_FILE, 'r', encoding='utf-8') as f: diff --git a/styles/website.css b/styles/website.css deleted file mode 100644 index aeb002a..0000000 --- a/styles/website.css +++ /dev/null @@ -1,8 +0,0 @@ -.page-toc { - float: none; -} - -.page-toc li:before { - content: "\00a0"; - margin-left: -24px; -}