Skip to content
This repository was archived by the owner on Feb 6, 2023. It is now read-only.

Documentation

Jump to bottom
Musa Morena Marcusso Manhães edited this page Jun 6, 2020 · 10 revisions

Documentation

Link: https://uuvsimulator.github.io/

The documentation pages are generated using GitHub Pages. For this the documentation is divided between

Setting up the sources files locally

It is first necessary to clone the uuv_simulator_docs repository. The generation of the documentation from Markdown to HTML is done by using MkDocs. To run the mkdocs and update the documentation pages, clone the repository as

git clone git@github.com:uuvsimulator/uuv_simulator_docs.git

First, install pydoc-markdown in the version 2.0.0 (due to most of the ROS dependencies being only available in Python 2.x, the processing of the Python modules to generate documentation has to be done in Python 2.x).

sudo pip2 install pydoc-markdown==2.0.0

Next, the create a Python venv with the necessary tools. Install sudo apt install python3-pip. Then run

sudo python3 -m pip install pip --upgrade # Update pip3
sudo pip3 install venv

# Create the virtual environment
cd uuv_simulator_docs
python3 -m venv venv
. venv/bin/activate
pip install -r requirements.txt

This will install mkdocs and other packages that compiles the documentation.

You will also need to install doxygen as

sudo apt install doxygen

and the tools to generate Markdown files from the Doxygen output. For that install npm using the instructions from this website. After the npm installation, run

npm install moxygen

In the next step, it is necessary to clone the uuvsimulator.github.io repository where the HTML files must be pushed to update the pages. To do this, run

cd uuv_simulator_docs
git clone https://github.com/uuvsimulator/uuvsimulator.github.io.git site

The site folder is ignored in the uuv_simulator_docs repository, so changes in there are going to be only related to the uuvsimualator.github.io repository.

Page structure

The configuration of the documentation page's structure can be seen in the mkdocs.yml. Updating any of the Markdown files in the docs folder will lead to changes in the GitHub Page after the documentation is compiled with mkdocs.

The main website structure is:

Main page

General information about the project, links to videos and badges to build status for each repository. This section includes information on package installation, quick start, useful bibliography and FAQ.

UUV Simulator

The documentation of the main uuv_simulator project. It includes user guide, overview of the packages, C++ and Python API documentations.

Plume Simulator

Documenation of the passive turbulent plume simulator.

RexROV 2

RexROV 2 model documentation.

ECA A9

ECA A9 AUV model documentation.

LAUV

LAUV model documentation.

Desistek SAGA ROV

Desistek SAGA ROV model documentation.

About

Mainly license information.

Build the page

To build the page, be sure to have built and sourced the following packages

  • uuv_simulator
  • rexrov2
  • desistek_saga
  • eca_a9
  • lauv_gazebo
  • uuv_plume_simulator

or use the vcs file as

cd $HOME/catkin_ws/src
vcs import < uuv_simulator_full.repos
rosdep update
rosdep install --from-paths src --ignore-src -r -y

then build and source the workspace.

To then generate the documentation pages, run

cd PATH/uuv_simulation_docs
./build

You can check the pages locally before pushing the changes by running

mkdocs serve

Updating uuv_simulator.github.io

After building the page, the HTML files will be stored in the site folder, which is already assigned as the local copy of the uuv_simulator.github.io. To push the changes, just run

cd site
git add .
git commit -s -m "Updating documentation"
git push origin master

Clone this wiki locally