Merge pull request #170 from purdue-arc/new-docs

More Documentation
purdue-arc · Apr 23, 2023 · 7a72132 · 7a72132
2 parents eec50d1 + 2bc90cd
commit 7a72132
Show file tree

Hide file tree

Showing 48 changed files with 1,524 additions and 689 deletions.
diff --git a/.gitignore b/.gitignore
@@ -74,6 +74,7 @@ docs/html/
 docs/autoapi
 docs/rosdoc/
 docs/rktl_*/
+~!docs/rktl_*/index.md
 
 # PyBuilder
 target/

diff --git a/docs/Makefile b/docs/Makefile
@@ -41,6 +41,7 @@ $(ROSDOC_OUT):
 	@mkdir -p $@
 	rosdoc_lite -o $@ $(shell rospack find $(notdir $@)) > /dev/null 2>&1
 	@# Clean up big unnecessary files 
+	@rm $@/html/index.html
 	@rm $@/html/*.png
 	@rm $@/html/*.js
 

diff --git a/docs/_static/favicons/android-chrome-192x192.png b/docs/_static/favicons/android-chrome-192x192.png
diff --git a/docs/_static/favicons/android-chrome-512x512.png b/docs/_static/favicons/android-chrome-512x512.png
diff --git a/docs/_static/favicons/apple-touch-icon.png b/docs/_static/favicons/apple-touch-icon.png
diff --git a/docs/_static/favicons/favicon-16x16.png b/docs/_static/favicons/favicon-16x16.png
diff --git a/docs/_static/favicons/favicon-32x32.png b/docs/_static/favicons/favicon-32x32.png
diff --git a/docs/_static/favicons/favicon.ico b/docs/_static/favicons/favicon.ico
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,6 +36,13 @@
     "sphinx.ext.intersphinx",
     "autoapi.extension",
     "myst_parser",
+    "sphinx_favicon",
+]
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "smartquotes",
 ]
 
 autoapi_dirs = [
@@ -77,3 +84,22 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_extra_path = ["rosdoc"]
+html_logo = "images/arc_logo.svg"
+
+favicons = [
+    {"href": "favicons/favicon.ico"},
+    {"href": "favicons/favicon-16x16.png"},
+    {"href": "favicons/favicon-32x32.png"},
+    {
+        "rel": "apple-touch-icon",
+        "href": "favicons/apple-touch-icon.png",
+    },
+    {
+        "rel": "android-chrome",
+        "href": "favicons/android-chrome-192x192.png",
+    },
+    {
+        "rel": "android-chrome",
+        "href": "favicons/android-chrome-512-512.png",
+    },
+]
diff --git a/docs/images/arc_logo.svg b/docs/images/arc_logo.svg
diff --git a/docs/index.md b/docs/index.md
@@ -1,9 +1,6 @@
 ```{include} ../README.md
 ```
 
-```{note}
-This project is under active development.
-```
 
 ```{toctree}
 :caption: Contents

diff --git a/docs/packages.rst b/docs/packages.rst
@@ -7,7 +7,7 @@ The repo is broken down into several
 
 .. toctree::
     :caption: Package Contents
-    :maxdepth: 4
+    :maxdepth: 2
     :glob:
 
     rktl_*
diff --git a/docs/requirements.in b/docs/requirements.in
@@ -2,3 +2,4 @@ Sphinx>=5,<6
 sphinx_rtd_theme
 myst_parser
 sphinx-autoapi
+sphinx-favicon
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,28 +2,28 @@
 # This file is autogenerated by pip-compile with Python 3.8
 # by the following command:
 #
-#    pip-compile requirements.in
+#    pip-compile --output-file==requirements.txt --resolver=backtracking requirements.in
 #
-alabaster==0.7.12
+alabaster==0.7.13
     # via sphinx
-astroid==2.15.1
+astroid==2.15.3
     # via sphinx-autoapi
-babel==2.10.3
+babel==2.12.1
     # via sphinx
-certifi==2022.6.15
+certifi==2022.12.7
     # via requests
-charset-normalizer==2.1.0
+charset-normalizer==3.1.0
     # via requests
-docutils==0.17.1
+docutils==0.18.1
     # via
     #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.3
+idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==6.1.0
+importlib-metadata==6.6.0
     # via sphinx
 jinja2==3.1.2
     # via
@@ -36,46 +36,50 @@ markdown-it-py==2.2.0
     # via
     #   mdit-py-plugins
     #   myst-parser
-markupsafe==2.1.1
+markupsafe==2.1.2
     # via jinja2
 mdit-py-plugins==0.3.5
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
 myst-parser==1.0.0
     # via -r requirements.in
-packaging==21.3
+packaging==23.1
     # via sphinx
-pygments==2.12.0
+pygments==2.15.1
     # via sphinx
-pyparsing==3.0.9
-    # via packaging
-pytz==2022.1
+pytz==2023.3
     # via babel
 pyyaml==6.0
     # via
     #   myst-parser
     #   sphinx-autoapi
-requests==2.28.1
+requests==2.28.2
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==5.0.2
+sphinx==5.3.0
     # via
     #   -r requirements.in
     #   myst-parser
     #   sphinx-autoapi
+    #   sphinx-favicon
     #   sphinx-rtd-theme
-sphinx-autoapi==2.0.1
+    #   sphinxcontrib-jquery
+sphinx-autoapi==2.1.0
     # via -r requirements.in
-sphinx-rtd-theme==1.0.0
+sphinx-favicon==1.0.1
     # via -r requirements.in
-sphinxcontrib-applehelp==1.0.2
+sphinx-rtd-theme==1.2.0
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-htmlhelp==2.0.1
     # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.3
@@ -86,7 +90,7 @@ typing-extensions==4.5.0
     # via astroid
 unidecode==1.3.6
     # via sphinx-autoapi
-urllib3==1.26.9
+urllib3==1.26.15
     # via requests
 wrapt==1.15.0
     # via astroid

diff --git a/docs/rktl_control.md b/docs/rktl_control.md
@@ -0,0 +1,11 @@
+```{include} ./rktl_control/README.md
+```
+
+```{toctree}
+:Caption: Package Contents
+:maxdepth: 2
+:glob:
+
+./rktl_control/*/README
+Msg/Srv Documentation </rktl_control/html/index-msg.html#http://>
+```
diff --git a/docs/rktl_perception.md b/docs/rktl_perception.md
@@ -0,0 +1,11 @@
+```{include} ./rktl_perception/README.md
+```
+
+```{toctree}
+:Caption: Package Contents
+:maxdepth: 2
+:glob:
+
+./rktl_perception/*/README
+Msg/Srv Documentation </rktl_perception/html/index-msg.html#http://>
+```
diff --git a/docs/templates/launch_README.md b/docs/templates/launch_README.md
@@ -7,23 +7,30 @@ using [roslaunch](https://wiki.ros.org/roslaunch):
 roslaunch <Package Name> <launch file>
 ```
 
-**Launch Files:**
-- [`my_launch_file.launch`](#my-launch-file-launch)
+```{contents} Launch Files in the package
+:depth: 2
+:backlinks: top
+:local: true
+```
 
 ---
 
 ## rocket_league.launch
-This roslaunch file launches launches multiple nodes or inlcudes other launch
-files, while posisbly also taking some arguments and setting some parameters.
+
+This roslaunch file launches launches multiple nodes or includes other launch
+files, while possibly also taking some arguments and setting some parameters.
 
 ### Launch Arguments
-- `arg1` (default: `true`): A boolean argument that determines something.
+
+- `arg1` (default: true): A boolean argument that determines something.
 
 ### Nodes
+
 - `node_name`: `foo` node from the `my_package` package
 - `node_namespace/node_name`: `bar` node from the `my_package` package
 
 ### Included Launch Files
+
 - `my_package foo.launch`
 - `my_package bar.launch` (Only included if `arg1` is set to `true`)
 

diff --git a/docs/templates/nodes_README.md b/docs/templates/nodes_README.md
@@ -8,24 +8,32 @@ by using `rosrun`:
 rosrun <Package_name> <Node name>
 ```
 
-**Nodes:**
-- [`node_name`](#node-name)
+```{contents} ROS Nodes in this package
+:depth: 2
+:backlinks: top
+:local: true
+```
 
 ---
 
 ## node_name
+
 This node tracks does something that you should explain here.
 
 ### Subscribed Topics:
+
 - `topic_foo` (my_pkg/MyMsg.msg): a topic that this node subscribes to
 
 ### Published Topics:
+
 - `topic_bar` (my_pkg/MyMsg.msg): a topic that this node publishes to
 
 ### Services:
+
 - `service_baz` (my_pkg/MySrv.srv): a service that does something
 
 ### Parameters:
+
 - `param` (`int`, default: `1`): A parameter that can be set.
 
 ---
diff --git a/docs/templates/package_README.md b/docs/templates/package_README.md
@@ -1,5 +1,6 @@
-# rktl_pacakge
+# rktl_package
+
 This package does something probably. This file would named
-`rktl_pacakge/README.md` and really not contain all that much. More detailed
+`rktl_package/README.md` and really not contain all that much. More detailed
 information would be provided in the other READMEs for this package. This is
 designed to give a high-level overview of this package's functionality.
diff --git a/rktl_autonomy/README.md b/rktl_autonomy/README.md
@@ -1,4 +1,5 @@
 # rktl_autonomy
+
 This package provides all code required to train a neural network to drive the
 car and interface it into the existing control structure. It also provides
 equivalent interfaces for two other environments (snake game and cartpole) for

diff --git a/rktl_autonomy/launch/README.md b/rktl_autonomy/launch/README.md
@@ -7,13 +7,11 @@ using [roslaunch](https://wiki.ros.org/roslaunch):
 roslaunch rktl_autonomy <launch file>
 ```
 
-**Launch Files:**
-
-- [`cartpole_train.launch`](#cartpole-train-launch)
-- [`rocket_league_agent.launch`](#rocket-league-agent-launch)
-- [`rocket_league_train.launch`](#rocket-league-train-launch)
-- [`snake_eval.launch`](#snake-eval-launch)
-- [`snake_train.launch`](#snake-train-launch)
+```{contents} Launch Files in the package
+:depth: 2
+:backlinks: top
+:local: true
+```
 
 ---