ft[docs]: Adds multiple docstrings and documentation website with exa…

…mples and automatically generated API.

.github/workflows/docs_pages.yaml

@@ -0,0 +1,69 @@
+name: Publish documentation
+on:
+  push:
+    tags: '*'
+    branches:
+      - main
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      #----------------------------------------------
+      #       check-out repo and set-up python
+      #----------------------------------------------
+      - name: Check out repository
+        uses: actions/checkout@v2
+      - name: Set up python
+        id: setup-python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      #----------------------------------------------
+      #  -----  install & configure poetry  -----
+      #----------------------------------------------
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+       #----------------------------------------------
+      #       load cached venv if cache exists
+      #----------------------------------------------
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+      #----------------------------------------------
+      # install dependencies if cache does not exist
+      #----------------------------------------------
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --with dev --no-interaction --no-root
+      #----------------------------------------------
+      # install your root project, if required
+      #----------------------------------------------
+      - name: Install library
+        run: poetry install --no-interaction
+      #----------------------------------------------
+      #              build documentation
+      #----------------------------------------------
+      # Runs a set of commands using the runners shell
+      - name: Build documentation
+        run: |
+          mkdir gh-pages
+          touch gh-pages/.nojekyll
+          cd docs/
+          poetry run sphinx-build -b html ./source _build
+          cp -r _build/* ../gh-pages/        
+
+      - name: Deploy documentation
+        if: ${{ github.event_name == 'push' }}
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: gh-pages

.pylintrc

@@ -426,6 +426,6 @@ valid-metaclass-classmethod-first-arg=mcs
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "Exception"
-overgeneral-exceptions=StandardError,
-                       Exception,
-                       BaseException
+overgeneral-exceptions=builtins.StandardError,
+                       builtins.Exception,
+                       builtins.BaseException

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)

docs/build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: af4e874c9ec7769c919948202a1d8a86
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/_modules/index.html

@@ -0,0 +1,124 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Overview: module code &mdash; mpscenes  documentation</title>
+      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
+
+
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+        <script src="../_static/jquery.js?v=5d32c60e"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js?v=b3ba4146"></script>
+        <script src="../_static/doctools.js?v=888ff710"></script>
+        <script src="../_static/sphinx_highlight.js?v=4825356b"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+
+
+
+          <a href="../index.html" class="icon icon-home">
+            mpscenes
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../getting_started.html">Getting started</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api.html">API</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">mpscenes</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
+      <li class="breadcrumb-item active">Overview: module code</li>
+      <li class="wy-breadcrumbs-aside">
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <h1>All modules for which code is available</h1>
+<ul><li><a href="mpscenes/common/analytic_trajectory.html">mpscenes.common.analytic_trajectory</a></li>
+<li><a href="mpscenes/common/component.html">mpscenes.common.component</a></li>
+<li><a href="mpscenes/common/errors.html">mpscenes.common.errors</a></li>
+<li><a href="mpscenes/common/reference_trajectory.html">mpscenes.common.reference_trajectory</a></li>
+<li><a href="mpscenes/common/spline_trajectory.html">mpscenes.common.spline_trajectory</a></li>
+<li><a href="mpscenes/goals/dynamic_sub_goal.html">mpscenes.goals.dynamic_sub_goal</a></li>
+<li><a href="mpscenes/goals/goal_composition.html">mpscenes.goals.goal_composition</a></li>
+<li><a href="mpscenes/goals/static_joint_space_sub_goal.html">mpscenes.goals.static_joint_space_sub_goal</a></li>
+<li><a href="mpscenes/goals/static_sub_goal.html">mpscenes.goals.static_sub_goal</a></li>
+<li><a href="mpscenes/goals/sub_goal.html">mpscenes.goals.sub_goal</a></li>
+<li><a href="mpscenes/goals/sub_goal_creator.html">mpscenes.goals.sub_goal_creator</a></li>
+<li><a href="mpscenes/obstacles/box_obstacle.html">mpscenes.obstacles.box_obstacle</a></li>
+<li><a href="mpscenes/obstacles/collision_obstacle.html">mpscenes.obstacles.collision_obstacle</a></li>
+<li><a href="mpscenes/obstacles/cylinder_obstacle.html">mpscenes.obstacles.cylinder_obstacle</a></li>
+<li><a href="mpscenes/obstacles/dynamic_box_obstacle.html">mpscenes.obstacles.dynamic_box_obstacle</a></li>
+<li><a href="mpscenes/obstacles/dynamic_cylinder_obstacle.html">mpscenes.obstacles.dynamic_cylinder_obstacle</a></li>
+<li><a href="mpscenes/obstacles/dynamic_obstacle.html">mpscenes.obstacles.dynamic_obstacle</a></li>
+<li><a href="mpscenes/obstacles/dynamic_sphere_obstacle.html">mpscenes.obstacles.dynamic_sphere_obstacle</a></li>
+<li><a href="mpscenes/obstacles/dynamic_urdf_obstacle.html">mpscenes.obstacles.dynamic_urdf_obstacle</a></li>
+<li><a href="mpscenes/obstacles/sphere_obstacle.html">mpscenes.obstacles.sphere_obstacle</a></li>
+<li><a href="mpscenes/obstacles/urdf_obstacle.html">mpscenes.obstacles.urdf_obstacle</a></li>
+</ul>
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2022, Max Spahn.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>