Skip to content

Commit

Permalink
Updated docs to 0.1.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeguzzi
jeguzzi committed Sep 27, 2024
1 parent 6719318 commit c4862ac
Show file tree
Hide file tree
Showing 183 changed files with 7,505 additions and 794 deletions.
99 changes: 99 additions & 0 deletions _sources/cli.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
======================
Command Line Interface
======================

Behind libraries for C++ and Python, navground provides commands.

.. warning::

As explained in :doc:`first_steps`, if you built navground from source, you need to source the setup script of the workspace where you installed it to enable the commands. Instead, if you installed navground using ``pip``, you can call Python commands without any setup.

You can call a ``<command>`` in up to four different ways, depending on the installation type and on package that implements the command.

``navground{_py} <command>`` [1]
``navground`` exposes the commands implemented in :doc:`packages/navground_sim` in C++, while ``navground_py`` exposes the commands implemented in :doc:`packages/navground_sim_py` in Python. The Python commands are a superset of the C++ commands.
``python -m navground.{core|sim} <command>`` [2]
``navground.core`` exposes the commands implemented in :doc:`packages/navground_core_py`, while ``navground.sim`` the the commands implemented in :doc:`packages/navground_sim_py`, i.e., the same commands as through ``navground_py``.
``install/lib/<package>/<command>`` [3]
stand-alone executables installed if you built from source.
``ros2 run <package> <command>`` [4]
ROS 2 short-cut to run command ``install/lib/<package>/<command>``, available only if you have ROS.

For example, listing the installed components, can be done in three equivalent ways:

.. tabs::

.. tab:: macOS and Linux

.. code-block:: bash
navground_py info
python3 -m navground.sim info
# only if you built from source
install/lib/navground_core_sim/info
# only if you have ROS
ros2 run navground_core_sim info
.. tab:: Windows

.. code-block:: bash
navground_py.exe info
python -m navground.sim info
# only if you built from source
install\Lib\navground_core_sim\info
# only if you have ROS
ros2 run navground_core_sim info
.. note::

In the rest of the documentation, when describing a <command>, we omit the prefix, only specifying the <command>, like

.. code-block:: console
info
for the previous example.

Commands
========

The following table summarizes all the available commands and how you can launch them.

.. table::
:widths: auto

+-------------------+---------------------+---------------------------------------------+
| package | commands | how to run them |
+===================+=====================+=============================================+
| navground_core | :ref:`info` | ``install/lib/navground_core/<command>`` |
| | | |
| | | ``ros2 run navground_core <command>`` |
+-------------------+---------------------+---------------------------------------------+
| navground_core_py | :ref:`info_py` | ``install/lib/navground_core_py/<command>`` |
| | | |
| | | ``ros2 run navground_core_py <command>`` |
| | | |
| | | ``python -m navground.core <command>`` |
+-------------------+---------------------+---------------------------------------------+
| navground_sim | :ref:`info_sim` | ``install/lib/navground_sim_py/<command>`` |
| | | |
| | :ref:`sample` | ``ros2 run navground_sim <command>`` |
| | | |
| | :ref:`run` | ``navground <command>`` |
+-------------------+---------------------+---------------------------------------------+
| navground_sim_py | :ref:`info_sim_py` | ``install/lib/navground_sim_py/<command>`` |
| | | |
| | :ref:`sample_py` | ``ros2 run navground_sim_py <command>`` |
| | | |
| | :ref:`run_py` | ``navground_py <command>`` |
| | | |
| | :ref:`run_rt` | ``python -m navground.sim <command>`` |
| | | |
| | :ref:`record_video` | |
| | | |
| | :ref:`replay` | |
+-------------------+---------------------+---------------------------------------------+



116 changes: 62 additions & 54 deletions _sources/first_steps.rst
View file
Original file line number Diff line number Diff line change
@@ -1,112 +1,122 @@
============
===========
First Steps
============

Preparation
===========

If you built navground from source, you need to source the setup script of the workspace where you installed it.
If you have installed navground, congratulations!

Let us check that it is working too.

If you built navground from source, you need to source the workspace.

.. tabs::

.. tab:: bash
.. tab:: macOS

.. code-block:: console
source ./install/setup.bash
. install/setup.zsh
.. tab:: zsh
.. tab:: Linux

.. code-block:: console
. install/setup.bash
source ./install/setup.zsh
.. tab:: Windows command shell
.. tab:: Windows

.. code-block:: console
install\setup.bat
Run ``navground_py``, which will have been installed by all types of installations.

Instead, if you installed navground using ``pip``, you don't need any setup but you are limited to the Python version of the commands (which is not a real limitation, as you Python commands are a superset of the C++ commands.)

Command Line Interface
======================

Navground has a modular architecture which users can extend by implementing new behaviors, kinematics, modulations, state estimation, tasks and scenarios. At installation, navground provides the implementation of several of these components so that you can start playing with them.
For instance, to list components available from C++, we can run

.. code-block:: console
.. tabs::

navground info
.. tab:: Linux & macOS

.. code-block:: console
You can list the other sub-commands with:
navground_py
.. code-block:: console
.. tab:: Windows

navground --help
.. code-block:: console
navground_py.exe
The Python package has few more sub-commands:
You should get a welcome message and few sub-commands to run.

.. code-block:: console
navground_py --help
usage: navground_py [-h] {info,run,run_rt,sample,record_video,replay} ...
Welcome to navground!
positional arguments:
{info,run,run_rt,sample,record_video,replay}
Subcommands
usage: navground_py [-h] {info,run,...} ...
options:
-h, --help show this help message and exit
.. note::

You can also launch ``navground_py`` from Python too.

.. code-block:: console
-h, --help show this help message and exit
Subcommands:
{info,run,...}
info Lists registered components.
run Runs an experiment using the Python interpreter
run_rt Runs an experiment using the Python interpreter in real-time.
sample Samples a world from a scenario.
record_video Make video from an experiment using the Python interpreter.
replay Replay an experiment in real-time.
python -m navground.sim --help
All commands are also available as standalone executables, installed in ``install/lib``:
Navground has a modular architecture which users can extend by implementing new behaviors, kinematics, modulations, state estimation, tasks and scenarios. At installation, navground provides the implementation of several of these components to play with. Calling ``info`` will list them

.. tabs::

.. tab:: macOS and Linux
.. tab:: Linux & macOS

.. code-block:: console
install/lib/<package>/<command>
navground_py info
.. tab:: Windows

.. code-block:: console
install\Lib\<package>\<command>
navground_py.exe info
and, if installed, from ROS 2
.. code-block:: console
ros2 run <package> <command>
.. note::

In the rest of the documentation, when describing commands, we omit ``ros2 run ...`` or the install path prefix and only specify the command to run, like
Behaviors
---------
Dummy, HL, HRVO, ORCA, PyDummy, SocialForce
Kinematics
----------
2WDiff, 2WDiffDyn, 4WOmni, Ahead, Omni
Modulations
-----------
LimitAcceleration, MotorPID, Relaxation
State Estimations
-----------------
Boundary, Bounded, Combination, Discs, Lidar, pyLidar
.. code-block:: console
Tasks
-----
Direction, Waypoints
info
Scenarios
---------
Antipodal, Corridor, Cross, CrossTorus, Simple
Next steps
==========

From here on, you may

want to go get familiar with the command line interface
read :doc:`cli`

want to go through some tutorials
start with :doc:`tutorials/tour`

Expand All @@ -120,5 +130,3 @@ want to check out the programming interfaces
have a look at :doc:`reference/index`




3 changes: 2 additions & 1 deletion _sources/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@ Welcome to navground's documentation!
:caption: Contents:

introduction
installation
installation/index
first_steps
cli
tutorials/tour
packages/index
tutorials/index
Expand Down
22 changes: 22 additions & 0 deletions _sources/installation/docker.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
======
Docker
======

We provide the following `docker files <https://github.com/idsia-robotics/navground/tree/main/docker>`_


.. list-table::
:widths: auto

* - ``Dockerfile.source-deps``
- Build from source navground and all dependencies in ``ubuntu:latest``
* - ``Dockerfile.binary-deps``
- Build from source navground and a minimal number of dependencies in ``ubuntu:latest``
* - ``Dockerfile.ros``
- Build from source navground in ``ros:latest``
* - ``Dockerfile.dev``
- Like ``Dockerfile.source-deps`` but keeping all the packages to build navground again
* - ``Dockerfile.python``
- Install the pre-built navground wheel in ``python:3.12-slim``
* - ``Dockerfile.notebook``
- Install the pre-built navground wheel in ``python:3.12-slim`` and everything needed to run the jupyter notebooks in `tutorials <https://github.com/idsia-robotics/navground/tree/main/docs/tutorials>`_:
Loading

0 comments on commit c4862ac

Please sign in to comment.