Add multiversion documentation for rolling/galactic and foxy (StoglRo…

…botics#35)
Robotgir · Feb 15, 2022 · 71c80dc · 71c80dc
1 parent a95fa8f
commit 71c80dc
Show file tree

Hide file tree

Showing 17 changed files with 416 additions and 132 deletions.
diff --git a/.github/workflows/docs-check-sphinx-pages.yml b/.github/workflows/docs-check-sphinx-pages.yml
@@ -0,0 +1,31 @@
+name: Build and Check Sphinx Page
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - master
+      - foxy
+
+jobs:
+  build-multiversion:
+    name: Check Multiversion
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: '3.8'
+        cache: 'pip'
+    - name: Install Python dependencies
+      run: |
+        cd docs/
+        python -m pip install --upgrade pip
+        pip install --upgrade --requirement requirements.txt
+    - name: Build multiversion
+      run: |
+        cd docs/
+        make multiversion
diff --git a/.github/workflows/docs-deploy-sphinx-pages.yml b/.github/workflows/docs-deploy-sphinx-pages.yml
@@ -0,0 +1,36 @@
+name: Build Check and Deploy Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+      - foxy
+
+jobs:
+  deploy-multiversion:
+    name: Deploy Multiversion
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: '3.8'
+        cache: 'pip'
+    - name: Install Python dependencies
+      run: |
+        cd docs/
+        python -m pip install --upgrade pip
+        pip install --upgrade --requirement requirements.txt
+    - name: Build multiversion
+      run: |
+        cd docs/
+        make multiversion
+    - name: Deploy Pages
+      if: ${{ success() }}
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html
diff --git a/.github/workflows/docs-sphinx-build-check.yml b/.github/workflows/docs-sphinx-build-check.yml
diff --git a/.github/workflows/docs-sphinx-make-page.yml b/.github/workflows/docs-sphinx-make-page.yml
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,17 +1,24 @@
 # Minimal makefile for Sphinx documentation
 #
+# $(0) is meant as shortcut for $(SPHINXOPTS) to pass them on cmd line
+#
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = python3 -m sphinx
 SOURCEDIR     = .
 BUILDDIR      = _build
+SPHINXOPTS    = -c .
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+multiversion: Makefile
+	sphinx-multiversion $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
+	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=master/index.html\" /></head></html>" > "$(BUILDDIR)"/html/index.html
+
+# https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
+.PHONY: help Makefile multiversion
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

diff --git a/docs/Readme.md b/docs/Readme.md
@@ -0,0 +1,27 @@
+# Ros_Team_workspace Documentation
+
+We use [sphinx](https://www.sphinx-doc.org/en/master/) for our docs. For the building of the multiversion docs  [sphinx-multiversion](https://holzhaus.github.io/sphinx-multiversion/master/index.html#) is used. The docs itself are written in [restructuredtext format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) (*.rst).
+
+## Installation and building
+### Installation
+If you want to edit the docs you first have to install all the required dependencies. From within the docs directory run:
+```bash
+python -m pip install -r requirements.txt
+```
+### Building
+After the requirements have been installed, the docs can then be build if you run:
+```bash
+make html
+```
+from within the `docs/` folder. You can then view the docs by opening the `docs/_build/html/index.html` in your browser. Changes you made should immediately be visible.
+
+### Building multiversion
+If you want to build multiversion docs you have to run:
+```bash
+make multiversion
+```
+from within the `docs/` folder. You can then view the docs by opening the `docs/_build/html/index.html`.
+| :exclamation:  Note   :exclamation:                                                                                                                              |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|However, be aware that changes to the multiversion docs only appear after committing them. If you want to see them immediate, you have to build using `make html`.|
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------
diff --git a/docs/_static/images/favicon-bg.png b/docs/_static/images/favicon-bg.png
diff --git a/docs/_static/images/foxy-small.png b/docs/_static/images/foxy-small.png
diff --git a/docs/_static/images/foxy.png b/docs/_static/images/foxy.png
diff --git a/docs/_static/images/galactic-small.png b/docs/_static/images/galactic-small.png
diff --git a/docs/_static/images/galactic.png b/docs/_static/images/galactic.png
diff --git a/docs/_static/images/logo.png b/docs/_static/images/logo.png
diff --git a/docs/_static/images/rolling-small.png b/docs/_static/images/rolling-small.png
diff --git a/docs/_static/images/rolling.png b/docs/_static/images/rolling.png
diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html
@@ -0,0 +1,29 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    <dl>
+      <dt>ROS Team Workspace - Galactic and Rolling</dt>
+      {%- for item in versions.in_development|sort(reverse=True) %}
+      <dd><a href="{{ item.url }}">{{ item.name|title }} (latest)</a></dd>
+      {%- endfor %}
+    </dl>
+    <dl>
+      <dt>ROS Team Workspace - Foxy</dt>
+      {%- for item in versions.releases|sort(reverse=True) %}
+        {%- if item.name == latest_version.name %}
+        <dd><a href="{{ item.url }}">{{ item.name|title }} (recommended)</a></dd>
+        {%- elif item.name in eol_versions %}
+        <dd><a href="{{ item.url }}">{{ item.name|title }} (EOL)</a></dd>
+        {% else %}
+        <dd><a href="{{ item.url }}">{{ item.name|title }}</a></dd>
+        {%- endif %}
+      {%- endfor %}
+   </dl>
+  </div>
+</div>
+{%- endif %}