Add readthedocs (#18)

* add doc files * action to trigger rtd build --------- Signed-off-by: Christian Henkel <[email protected]>
boschresearch · Aug 13, 2024 · 7c32eb5 · 7c32eb5
1 parent c43aaa5
commit 7c32eb5
Show file tree

Hide file tree

Showing 26 changed files with 180 additions and 33 deletions.
diff --git a/.github/workflows/rtd.yaml b/.github/workflows/rtd.yaml
@@ -0,0 +1,18 @@
+# Workflow to trigger ReadTheDocs build on every push to main branch
+
+name: rtd
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+        - name: Trigger RTDs build
+          run: |
+            curl 
+            -X POST "https://readthedocs.org/api/v3/projects/bt_tools/versions/latest/builds/" \
+            -H "Authorization: Token ${{ secrets.RTD_API_TOKEN }}"
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
 __pycache__/
 *.py[cod]
-.tmp_imgs/
+.tmp_imgs/
+docs/build/
+docs/source/apidocs/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,13 @@
+version: "2"
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py
diff --git a/README.md b/README.md
@@ -7,11 +7,11 @@
 [![python](https://img.shields.io/github/languages/top/boschresearch/bt_tools.svg?style=flat-square)](https://github.com/boschresearch/bt_tools/search?l=python)
 [![License](https://img.shields.io/badge/license-Apache%202-blue.svg?style=flat-square)](https://github.com/boschresearch/bt_tools/blob/main/LICENSE)
 
-<img src="bt_tools_common/doc/logo.png" alt="bt_tools logo" width="200"/>
+<img src="imgs/logo.png" alt="bt_tools logo" width="200"/>
 
 __bt_tools__ is a collection of software for working with behavior trees (BTs) in ROS. It contains means for interpreting, visualizing and introspecting BTs.
 
-![bt_tools](bt_tools_common/doc/overview.drawio.svg)
+![bt_tools](imgs/overview.drawio.svg)
 
 ## btlib
 
@@ -38,7 +38,7 @@ ros2 run bt_live bt_live --ros-args -p fbl_file:=<path_to_fbl_log>
 Then open a browser at <http://localhost:8000> to see the visualization.
 It should look a little something like this:
 
-<img src="bt_live/doc/bt_live_browser.png" width="600" />
+<img src="imgs/bt_live_browser.png" width="600" />
 
 ## bt_view
 
@@ -58,7 +58,7 @@ to the same folder that the `fbl` log is in.
 
 For example, the `_states.png` file will look like this:
 
-<img src="bt_view/test/_test_data/reference/bt_trace_other_fbl_log_states.png" width="600" />
+<img src="imgs/bt_trace_other_fbl_log_states.png" width="600" />
 
 ### Calculate coverage
 

diff --git a/bt_live/src/bt_live/__init__.py b/bt_live/src/bt_live/__init__.py
@@ -0,0 +1,3 @@
+"""
+Visualize behavior tree in real-time.
+"""
diff --git a/bt_tools_common/CMakeLists.txt b/bt_tools_common/CMakeLists.txt
diff --git a/bt_tools_common/package.xml b/bt_tools_common/package.xml
diff --git a/bt_view/src/bt_view/__init__.py b/bt_view/src/bt_view/__init__.py
@@ -0,0 +1,3 @@
+"""
+Render behavior trees to images files.
+"""
diff --git a/btlib/log/COLCON_IGNORE b/btlib/log/COLCON_IGNORE
diff --git a/btlib/log/latest b/btlib/log/latest
@@ -0,0 +1 @@
+latest_list
diff --git a/btlib/log/latest_list b/btlib/log/latest_list
@@ -0,0 +1 @@
+list_2024-07-31_11-20-41
diff --git a/btlib/src/btlib/__init__.py b/btlib/src/btlib/__init__.py
@@ -1,3 +1,7 @@
+"""
+Module to visualize behavior trees.
+"""
+
 from typing import Dict, List, Optional
 
 from bs4 import BeautifulSoup

diff --git a/btlib/src/btlib/logs.py b/btlib/src/btlib/logs.py
@@ -53,9 +53,8 @@ def read_log_fbl(fname: str,
     :param g: Graph representing the behavior tree.
 
     :return: Tuple of
-        values_count: How often a node was executed.
-        values_success: How often a node was successful
-            (positive value) vs failed (negative value)
+        `values_count`: How often a node was executed.
+        `values_success`: How often a node was successful (positive value) vs failed (negative value).
     """
     with open(fname, 'rb') as file_b:
         buf = bytearray(file_b.read())
@@ -79,7 +78,11 @@ def merge_values(
     values1: Optional[Union[VALUE_MAP, VALUE_MAP_RETURN_STATES]],
     values2: Optional[Union[VALUE_MAP, VALUE_MAP_RETURN_STATES]]) -> \
         Union[VALUE_MAP, VALUE_MAP_RETURN_STATES]:
-    """Merge values."""
+    """
+    Merge values of two value maps.
+
+    On the lowest level this will add the two values if they are present.
+    """
     if values1 is None:
         assert values2 is not None, 'At least one values must not be None'
         return values2

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 @@
+sphinx<8.0.0
+sphinx-rtd-theme==2.0.0
+
+sphinx-autodoc2==0.5.0
+myst-parser==4.0.0
+sphinx-mdinclude==0.6.2
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+project = 'bt_tools'
+copyright = '2024, Robert Bosch GmbH'
+author = 'Christian Henkel'
+
+release = '0.1'
+version = '0.1.0'
+
+# -- General configuration
+extensions = [
+    'autodoc2',
+    'sphinx_mdinclude',
+]
+templates_path = ['_templates']
+
+# -- HTML Theming
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'logo_only': True,
+    'display_version': False,
+    'style_nav_header_background': '#364C3B'  # Dark contrast to the logo
+}
+html_logo = 'logo.png'
+html_extra_path = ['../../']
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+autodoc2_packages = [
+    "../../btlib/src/btlib",
+    "../../bt_view/src/bt_view",
+    "../../bt_live/src/bt_live",
+]
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,12 @@
+Welcome to my RTD demo
+======================
+
+.. mdinclude:: ../../README.md
+
+Contents
+--------
+
+.. toctree::
+
+   tutorials
+   apidocs/index
diff --git a/bt_tools_common/doc/logo.png → docs/source/logo.png b/bt_tools_common/doc/logo.png → docs/source/logo.png
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -0,0 +1,15 @@
+Tutorials
+=========
+
+How to model check your robot
+-----------------------------
+
+1. Install the necessary packages:
+```
+sudo apt install THAT
+```
+
+2. Run the model checker:
+```
+convince_toolchain -i model.scxml -o results.json
+```
diff --git a/bt_live/doc/bt_live_browser.png → imgs/bt_live_browser.png b/bt_live/doc/bt_live_browser.png → imgs/bt_live_browser.png
diff --git a/imgs/bt_trace_other_fbl_log_states.png b/imgs/bt_trace_other_fbl_log_states.png
diff --git a/imgs/logo.png b/imgs/logo.png
diff --git a/bt_tools_common/doc/logo.svg → imgs/logo.svg b/bt_tools_common/doc/logo.svg → imgs/logo.svg
diff --git a/bt_tools_common/doc/logo32p.png → imgs/logo32p.png b/bt_tools_common/doc/logo32p.png → imgs/logo32p.png
diff --git a/bt_tools_common/doc/overview.drawio.svg → imgs/overview.drawio.svg b/bt_tools_common/doc/overview.drawio.svg → imgs/overview.drawio.svg