Skip to content

Commit

Permalink
Merge pull request #94 from ami-iit/docs
Browse files Browse the repository at this point in the history
Add docs with read the docs
  • Loading branch information
Giulero authored Jul 9, 2024
2 parents 7eac7f2 + 29d78f5 commit 7c855ca
Show file tree
Hide file tree
Showing 33 changed files with 920 additions and 7 deletions.
20 changes: 20 additions & 0 deletions .github/workflows/read_the_docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
name: Read the Docs
on:
pull_request_target:
types:
- opened
# Execute this action only on PRs that touch
# documentation files.
# paths:
# - "docs/**"

permissions:
pull-requests: write

jobs:
documentation-links:
runs-on: ubuntu-latest
steps:
- uses: readthedocs/actions/preview@v1
with:
project-slug: "adam-docs"
37 changes: 37 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.12"
# You can also specify other tool versions:
# nodejs: "20"
# rust: "1.70"
# golang: "1.20"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/conf.py
# You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
# builder: "dirhtml"
# Fail on all warnings to avoid broken references
# fail_on_warning: true

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: docs/requirements.txt

formats: all
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
33 changes: 33 additions & 0 deletions docs/_templates/custom-class-template.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
:members:
:show-inheritance:
:private-members:
:undoc-members:

{% block methods %}
.. automethod:: __init__

{% if methods %}
.. rubric:: {{ _('Methods') }}

.. autosummary::
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}

.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
75 changes: 75 additions & 0 deletions docs/_templates/custom-module-template.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}

{% block attributes %}
{% if attributes %}
.. rubric:: Module Attributes

.. autosummary::
:toctree:
{% for item in attributes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block classes %}
{% if classes %}
.. rubric:: {{ _('Classes') }}

.. autosummary::
:toctree:
:template: custom-class-template.rst
{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block inheritance %}
{% if classes %}

.. inheritance-diagram:: {{ fullname }}
:caption: Inheritance Relationship
:parts: -1
{% endif %}
{% endblock %}

{% block functions %}
{% if functions %}
.. rubric:: {{ _('Functions') }}

.. autosummary::
:toctree:
{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block exceptions %}
{% if exceptions %}
.. rubric:: {{ _('Exceptions') }}

.. autosummary::
:toctree:
{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
:toctree:
:template: custom-module-template.rst
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
82 changes: 82 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import os
import subprocess
import sys

import adam

sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))
sys.path.insert(0, os.path.abspath("../../"))
sys.path.insert(0, os.path.abspath("../src/"))

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "adam"
copyright = "2021, Artificial and Mechanical Intelligence Lab"
author = "Artificial and Mechanical Intelligence Lab"
# get release from git tag

release = (
subprocess.check_output(["git", "describe", "--tags", "--always"]).decode().strip()
)


# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
"sphinx.ext.duration",
"sphinx.ext.doctest",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
# "sphinx.ext.inheritance_diagram",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
# "sphinx.ext.autosectionlabel",
"sphinx_copybutton",
"myst_parser",
"sphinx.ext.napoleon",
"autoapi.extension",
]

autoapi_dirs = ["../src/"]

source_suffix = {
".rst": "restructuredtext",
".txt": "markdown",
".md": "markdown",
}

autosummary_generate = True
autodoc_member_order = "bysource"

templates_path = ["_templates"]
exclude_patterns = []

html_title = f"adam"


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "sphinx_book_theme"
# html_theme = "sphinx_rtd_theme"

# html_theme = "furo"
# html_logo = "pirati.png"

html_context = {
"display_github": True,
"github_user": "TOB-KNPOB",
"github_repo": "Jabref2Obsdian",
"github_version": "main",
"conf_py_path": "/docs/",
}

html_static_path = ["_static"]
51 changes: 51 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
.. adam documentation master file, created by
sphinx-quickstart on Fri Jun 28 14:10:15 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
adam
----

**Automatic Differentiation for rigid-body-dynamics AlgorithMs**

**adam** implements a collection of algorithms for calculating rigid-body dynamics for **floating-base** robots, in mixed and body fixed representations using:

.. create rst list with links to the following libraries
- `Jax <https://github.com/google/jax>`_
- `CasADi <https://web.casadi.org/>`_
- `PyTorch <https://github.com/pytorch/pytorch>`_
- `NumPy <https://numpy.org/>`_


**adam** employs the automatic differentiation capabilities of these frameworks to compute, if needed, gradients, Jacobian, Hessians of rigid-body dynamics quantities. This approach enables the design of optimal control and reinforcement learning strategies in robotics.
Thanks to the `jax.vmap`-ing and `jax.jit`-ing capabilities, the algorithms can be run on batches of inputs, which are possibly converted to PyTorch using the `jax2torch` conversion functions.


**adam** is based on **Roy Featherstone's Rigid Body Dynamics Algorithms**.

Examples
--------

Have a look at the examples `folder in the repository <https://github.com/ami-iit/adam/tree/main/examples>`_!


License
-------

`BSD-3-Clause <https://choosealicense.com/licenses/bsd-3-clause/>`_


.. toctree::
:maxdepth: 2
:caption: Getting started:

installation
quickstart/index

.. toctree::
:maxdepth: 2
:caption: API:

modules/index
34 changes: 34 additions & 0 deletions docs/installation.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
Installation
============
This is the installation guide for the project.


Prerequisites
-------------

adam requires python 3.7 or later.


🐍 Conda installation
---------------------

We suggest to install adam using `conda <https://anaconda.org/>`_:

.. code-block:: bash
conda install adam-robotics -c conda-forge
📦 Pip installation
--------------------

You can also install adam using `pip <https://pypi.org/project/pip/>`_:

.. code-block:: bash
pip install adam-robotics
If you want to install all the dependencies install ``adam-robotics[all]``.

.. note::

If the GPU support for ``JAX`` is needed, follow the instructions in the `Jax documentation <https://jax.readthedocs.io/en/latest/installation.html#conda-community-supported>`_.
35 changes: 35 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
Loading

0 comments on commit 7c855ca

Please sign in to comment.