refactor(docs, launch, nodes): Update Sphinx docs [skip ci]

Refactors launch and ROS parameters to be more intuitive and easy to use.

Author: hmakelin

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contribute
 
 All kinds of contributions are welcome, from raising issues and improvement suggestions with the software to software 
-commits and pull requests (PRs). Please see below for guidance and suggestions on how and where to contribute.
+commits and pull requests (PRs). Please see below for guidance and suggestions on how to contribute.
 
 ## Issues and improvement suggestions
 
@@ -12,51 +12,33 @@ you could add your own comments. If not, use the provided templates to submit a
 
 ## Pull requests and software commits
 
-> **Note**
+> **Warning**
 > By contributing to this repository, you agree that **your contributions will be licensed under the repository's MIT 
 > license**.
 
 All changes to the software are made through [pull requests][2]. Please pay attention to the following before you 
 submit your pull request:
 
+* See [Style Guide for Python Code][4] for general code style guidelines.
+
+* Consider following [Conventional Commits][3] when making your commit message.
+
 * If your pull request is related to an existing [open issue][1], please mention it in your pull request description.
 
 * If your pull request addresses a new issue or improvement, consider posting it on the [open issues][1] page before 
   you start working on it so that others will also be aware of your pending work.
 
-* If your pull request makes use of 3rd party software, please ensure that it is MIT license compatible.
-
-* Consider creating a [draft pull request][3] to get early feedback on your work before you commit to it further.
+* Consider creating a [draft pull request][5] to get early feedback on your work before you commit to it further.
 
 * In your pull request, please describe not only *what* you have done, but also *why* you have done it. This helps the 
   reviewer understand your thought process faster.
 
-## Improvements and new features
-
-If you are planning to add a new feature or improve an existing feature of the software, please ensure that your 
-contribution is aligned with GISNav's **development focus**. Currently the **development focus** is to make the software:
-
-* **Easier to use**, for example by...
-  * ...improving documentation
-  * ...streamlining the public API
-  * ...smoothing out configuration quirks
-* **Better tested**, for example by...
-  * ...improving unit test coverage
-  * ...adding a (better) testing framework
-* **Support relevant technology stacks**, for example by...
-  * ...adding support for Ardupilot
-  * ...adding an adapter for TensorFlow-based neural networks
-* **More accurate**, for example by...
-  * ...adding a new state-of-the art pose estimation algorithm
-  * ...making use of digital-elevation maps (DEM) to retrieve elevation of ground plane
-  * ...making use of the [OSM buildings][4] database to remove assumption of planar ground surface
-
-> **Note**
-> Please consider the examples in the second level bullet points as *suggestions* on where to find low-hanging fruit rather than 
-> as *recommendations* on what to do.
+* If your pull request makes use of 3rd party software, please ensure that it is MIT license compatible.
 
 [2]: https://docs.github.com/en/pull-requests
 
-[3]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
+[3]: https://www.conventionalcommits.org/
+
+[4]: https://peps.python.org/pep-0008/
 
-[4]: https://osmbuildings.org/data/
+[5]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests

README.md

@@ -2,7 +2,7 @@ https://user-images.githubusercontent.com/22712178/187902004-480397cc-460f-4d57-
 
 # Introduction
 
-> **Warning** Do not use this software for real drone flights. This software is untested and has only been demonstrated
+> **Warning** Do not use this software for real drone flights. GISNav is untested and has only been demonstrated
 > in a software-in-the-loop (SITL) simulation environment.
 
 GISNav is a ROS 2 package that enables map-based visual navigation for airborne drones **in a simulation environment**.

docs/_static/img/gisnav_sitl_featureless_buildings.png

@@ -37,7 +37,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'autodocsumm', 'myst_parser']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.coverage',
+              'sphinx.ext.autosectionlabel',
+              'sphinx_design',
+              'autodocsumm',
+              'myst_parser'
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -79,6 +85,7 @@
         }
     ],
     "icon_links_label": "Quick Links",
+    "show_toc_level": 3,
 }
 
 # Make version number accessible in .rst files

docs/conf.py

@@ -3,27 +3,38 @@ GISNav Developer Documentation
 #####################################
 Welcome to GISNav's developer documentation!
 
-This site contains the following pages:
+.. card:: Get Started
+    :link: pages/get_started.html
 
-* `Get Started <pages/get_started.html>`_
+    A quick demonstration of GNSS-free visual navigation with GISNav
 
-    A quick demonstration of GNSS-free visual navigation with GISNav's :class:`.MockGPSNode`
+.. card:: Developer Guide
+    :link: pages/developer_guide/index.html
 
-* `Setup <pages/setup.html>`_
+    Instructions on how to integrate GISNav with your own project and how to extend its functionality
 
-    Instructions on how to to setup your own PX4 development and simulation environment
+.. card:: API Documentation
+    :link: pages/api_documentation/index.html
 
-* `Developer Guide <pages/developer_guide.html>`_
+    GISNav public API reference for developers
 
-    Instructions on how to integrate GISNav with your own project and how to extend its functionality
+.. card:: Contribute
+    :link: pages/contribute.html
 
-* `API Documentation <pages/api_documentation.html>`_
+    Contributions to GISNav are welcome! Please see this page for guidance
 
-    GISNav public API reference for developers
+Generate documentation
+_________________________________________
+To build this Sphinx documentation yourself, first install the :ref:`GISNav ROS package` including the
+:ref:`Development dependencies` and then run:
+
+.. code-block:: bash
+    :caption: Build Sphinx documentation
 
-* `Contribute <pages/contribute.html>`_
+    cd ~/colcon_ws/src/gisnav/docs
+    make html
 
-    Contributions to GISNav are welcome! Please see this page for guidance.
+The HTML documentation will then appear in the ``~/colcon_ws/src/gisnav/docs/_build/`` folder.
 
 .. seealso::
 
@@ -39,7 +50,6 @@ This site contains the following pages:
    :hidden:
 
    pages/get_started
-   pages/setup
-   pages/developer_guide
-   pages/api_documentation
+   pages/developer_guide/index
+   pages/api_documentation/index
    pages/contribute

docs/index.rst

@@ -0,0 +1,35 @@
+gisnav
+--------------------------------------------
+.. automodule:: gisnav
+   :autosummary:
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :show-inheritance:
+
+assertions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gisnav.assertions
+   :autosummary:
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :show-inheritance:
+
+data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gisnav.data
+   :autosummary:
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :show-inheritance:
+
+geo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gisnav.geo
+   :autosummary:
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :show-inheritance:

docs/pages/api_documentation.rst

@@ -0,0 +1,18 @@
+**************************************************
+API Documentation
+**************************************************
+Here you can find the automatically generated **public API** documentation for the `GISNav ROS 2 package`_. Use the
+search bar or the below module index to find what you are looking for.
+
+.. _GISNav ROS 2 package: https://github.com/hmakelin/gisnav
+
+.. warning::
+    GISNav is under active development and stability of the API is not guaranteed. Use a specific commit or version tag
+    to mitigate the impact of breaking changes.
+
+.. toctree::
+    :caption: Python module index
+
+    common_automodule
+    nodes/automodule
+    pose_estimators/automodule