[Docs] First instance of basic docs (#85)

matteobettini · web-flow · commit 179a07e3e9af · 2024-03-01T11:49:47.000Z
* docs

* amend

* Upload coverage

* Badges

* docs

* docs

* amend

* amend

* amend

* amend

* amend

* amend

* amend
diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml
@@ -47,6 +47,7 @@ jobs:
         pip install pytest-cov
         pip install tqdm
         pytest tests/ --doctest-modules --junitxml=junit/test-results.xml --cov=. --cov-report=xml --cov-report=html
+
     - if: matrix.python-version == '3.10'
       name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,8 @@
+# Docs
+docs/output/
+docs/source/generated/
+docs/build/
+
 ### JetBrains template
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -2,7 +2,6 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.0.1
     hooks:
-      - id: check-docstring-first
       - id: check-toml
       - id: check-yaml
         exclude: packaging/.*
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# 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.10"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   fail_on_warning: true
+   configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+    - 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
+    # Install our python package before building the docs
+    - method: pip
+      path: .
diff --git a/README.md b/README.md
@@ -2,8 +2,12 @@
 <a href="https://pypi.org/project/vmas"><img src="https://img.shields.io/pypi/v/vmas" alt="pypi version"></a>
 [![Downloads](https://static.pepy.tech/personalized-badge/vmas?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads)](https://pepy.tech/project/vmas)
 ![tests](https://github.com/proroklab/VectorizedMultiAgentSimulator/actions/workflows/python-app.yml/badge.svg)
+[![codecov](https://codecov.io/github/proroklab/VectorizedMultiAgentSimulator/coverage.svg?branch=main)](https://codecov.io/gh/proroklab/VectorizedMultiAgentSimulator)
+[![Documentation Status](https://readthedocs.org/projects/vmas/badge/?version=latest)](https://vmas.readthedocs.io/en/latest/?badge=latest)
 [![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10-blue.svg)](https://www.python.org/downloads/)
 [![GitHub license](https://img.shields.io/badge/license-GPLv3.0-blue.svg)](https://github.com/proroklab/VectorizedMultiAgentSimulator/blob/main/LICENSE)
+[![arXiv](https://img.shields.io/badge/arXiv-2207.03530-b31b1b.svg)](https://arxiv.org/abs/2207.03530)
+
 
 <p align="center">
 <img src="https://github.com/matteobettini/vmas-media/blob/main/media/VMAS_scenarios.gif?raw=true" alt="drawing"/>  
diff --git a/docs/Makefile b/docs/Makefile
@@ -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     = source
+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)
diff --git a/docs/make.bat b/docs/make.bat
@@ -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
+
+if "%1" == "" goto help
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,6 @@
+git+https://github.com/matteobettini/benchmarl_sphinx_theme.git
+numpy
+torch
+pyglet<=1.5.27
+gym
+six
diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst
@@ -0,0 +1,9 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+   :undoc-members:
+   :inherited-members:
diff --git a/docs/source/_templates/autosummary/class_no_inherit.rst b/docs/source/_templates/autosummary/class_no_inherit.rst
@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+   :undoc-members:
diff --git a/docs/source/_templates/autosummary/class_no_undoc.rst b/docs/source/_templates/autosummary/class_no_undoc.rst
@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+   :inherited-members:
diff --git a/docs/source/_templates/autosummary/class_private.rst b/docs/source/_templates/autosummary/class_private.rst
@@ -0,0 +1,9 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/source/_templates/autosummary/class_private_no_undoc.rst b/docs/source/_templates/autosummary/class_private_no_undoc.rst
@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+   :private-members:
diff --git a/docs/source/_templates/breadcrumbs.html b/docs/source/_templates/breadcrumbs.html
@@ -0,0 +1,8 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+{% endblock %}<!--
+  ~ Copyright (c) 2024.
+  ~ ProrokLab (https://www.proroklab.org/)
+  ~ All rights reserved.
+  -->
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,72 @@
+#  Copyright (c) 2024.
+#  ProrokLab (https://www.proroklab.org/)
+#  All rights reserved.
+
+# Configuration file for the Sphinx documentation builder.
+import os.path as osp
+import sys
+
+import benchmarl_sphinx_theme
+
+import vmas
+
+# -- Project information
+
+project = "VMAS"
+copyright = "ProrokLab"
+author = "Matteo Bettini"
+version = vmas.__version__
+
+
+# -- General configuration
+sys.path.append(osp.join(osp.dirname(benchmarl_sphinx_theme.__file__), "extension"))
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "patch",
+]
+
+add_module_names = False
+autodoc_member_order = "bysource"
+toc_object_entries = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+    "torch": ("https://pytorch.org/docs/master", None),
+    "torchrl": ("https://pytorch.org/rl", None),
+    "tensordict": ("https://pytorch.org/tensordict", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+html_static_path = [osp.join(osp.dirname(benchmarl_sphinx_theme.__file__), "static")]
+
+
+html_theme = "sphinx_rtd_theme"
+# html_logo = (
+#     "https://raw.githubusercontent.com/matteobettini/benchmarl_sphinx_theme/master/benchmarl"
+#     "_sphinx_theme/static/img/benchmarl_logo.png"
+# )
+html_theme_options = {"logo_only": False, "navigation_depth": 2}
+# html_favicon = ('')
+html_css_files = [
+    "css/mytheme.css",
+]
+
+# -- Options for EPUB output
+epub_show_urls = "footnote"
+
+
+def setup(app):
+    def rst_jinja_render(app, _, source):
+        rst_context = {"vmas": vmas}
+        source[0] = app.builder.templates.render_string(source[0], rst_context)
+
+    app.connect("source-read", rst_jinja_render)
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,42 @@
+
+VMAS
+====
+
+Docs are currently being written, please bear with us.
+
+Forthcoming doc sections:
+
+- Usage
+    - Notebooks
+    - Installing
+    - Running
+    - Citing
+
+- Concepts (explanation of all the lib features) (divide in basic, advanced and medium)
+    - Input and output spaces
+    - Resetting and vectorization (which properties are vectorized)
+    - Implementing your scenario
+    - Customizing entities
+    - Controllers
+    - Dynamics models
+    - Communication actions
+    - Extra actions
+    - Customizing the world
+    - Sensors
+    - Joints
+    - Differentiability
+    - Rendering
+    - Plot function under rendering
+    - Interactive rendering
+
+- Scenarios description and renderings
+
+- Full package reference with docstrings for all public functions
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Package Reference
+
+   modules/root
+   modules/simulator
diff --git a/docs/source/modules/root.rst b/docs/source/modules/root.rst
@@ -0,0 +1,6 @@
+vmas
+====
+
+
+.. automodule:: vmas
+    :members:
diff --git a/docs/source/modules/simulator.rst b/docs/source/modules/simulator.rst
@@ -0,0 +1,19 @@
+vmas.simulator
+==============
+
+.. currentmodule:: vmas.simulator
+
+.. contents:: Contents
+    :local:
+
+Scenario
+--------
+
+.. currentmodule:: vmas.simulator.scenario
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated
+   :template: autosummary/class_no_undoc.rst
+
+   BaseScenario
diff --git a/vmas/__init__.py b/vmas/__init__.py
@@ -1,4 +1,4 @@
-#  Copyright (c) 2022-2023.
+#  Copyright (c) 2022-2024.
 #  ProrokLab (https://www.proroklab.org/)
 #  All rights reserved.
 
@@ -13,12 +13,13 @@
 __all__ = [
     "make_env",
     "render_interactively",
-    "Wrapper",
     "scenarios",
     "debug_scenarios",
     "mpe_scenarios",
 ]
 
+__version__ = "1.4.0"
+
 scenarios = sorted(
     [
         "dropout",
@@ -43,6 +44,7 @@
         "wind_flocking",
     ]
 )
+"""List of the vmas scenarios (excluding MPE and debug)"""
 
 debug_scenarios = sorted(
     [
@@ -56,8 +58,11 @@
         "diff_drive",
         "kinematic_bicycle",
         "pollock",
+        "drone",
     ]
 )
+"""List of the vmas debug scenarios """
+
 
 mpe_scenarios = sorted(
     [
@@ -72,3 +77,4 @@
         "simple_world_comm",
     ]
 )
+"""List of the vmas MPE scenarios """
diff --git a/vmas/examples/rllib.py b/vmas/examples/rllib.py
@@ -17,7 +17,8 @@
 from ray.tune import register_env
 from ray.tune.integration.wandb import WandbLoggerCallback
 
-from vmas import make_env, Wrapper
+from vmas import make_env
+from vmas.simulator.environment import Wrapper
 
 scenario_name = "balance"
 
diff --git a/vmas/interactive_rendering.py b/vmas/interactive_rendering.py
diff --git a/vmas/make_env.py b/vmas/make_env.py
diff --git a/vmas/scenarios/debug/vel_control.py b/vmas/scenarios/debug/vel_control.py
diff --git a/vmas/simulator/controllers/velocity_controller.py b/vmas/simulator/controllers/velocity_controller.py
diff --git a/vmas/simulator/environment/environment.py b/vmas/simulator/environment/environment.py
diff --git a/vmas/simulator/environment/rllib.py b/vmas/simulator/environment/rllib.py
diff --git a/vmas/simulator/scenario.py b/vmas/simulator/scenario.py

-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +git+https://github.com/matteobettini/benchmarl_sphinx_theme.git
 +numpy
 +torch
 +pyglet<=1.5.27
 +gym
 +six