Autogenerate java docs

.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+name: "CI Docs"
+
+on:
+  push:
+    branches:
+    - latest
+    tags:       
+    - '**'
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.7
+    - name: Set up Doxygen
+      run: sudo apt-get install doxygen
+    - name: Build Sphinx docs
+      run: |
+        export PATH=$PATH:~/.local/bin
+        cd docs
+        make multiversion
+    - name: Build Doxygen docs
+      run: |
+        ./docs/_utils/doxygen.sh
+    - name: Deploy
+      run : ./docs/_utils/deploy.sh
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        LATEST_VERSION: latest

.gitignore

@@ -4,8 +4,9 @@ testing/
 .settings
 .classpath
 .project
-doc
-docs
+docs/_build
+html
+latex
 notes
 .DS_Store
 

README-dev.rst

@@ -0,0 +1,36 @@
+Building the Docs
+=================
+
+*Note*: The docs build instructions have been tested with Sphinx 2.4.4 and Fedora 32.
+
+To build and preview the docs locally, you will need to install the following software:
+
+- `Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
+- `Python 3.7 <https://www.python.org/downloads/>`_
+- `pip <https://pip.pypa.io/en/stable/installing/>`_
+- `doxygen <https://www.tutorialspoint.com/how-to-install-doxygen-on-ubuntu/>`_
+
+Run the following command to build the docs.
+
+.. code:: console
+
+    cd docs
+    make preview
+
+Once the command completes processing, open http://127.0.0.1:5500/ with your preferred browser.
+
+Building multiple documentation versions
+========================================
+
+Build Sphinx docs for all the versions defined in ``docs/conf.py``.
+
+The multiverson command does not build doxygen docs.
+
+```
+cd docs
+make multiversion
+```
+
+Then, open ``docs/_build/dirhtml/<version>/index.html`` with your preferred browser.
+
+**NOTE:** If you only can see docs generated for the master branch, try to run ``git fetch --tags`` to download the latest tags from remote.

docs/Makefile

@@ -0,0 +1,72 @@
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = poetry run sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: all
+all: dirhtml
+
+.PHONY: pristine
+pristine: clean
+	git clean -dfX
+
+.PHONY: setup
+setup:
+	./_utils/setup.sh
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: preview
+preview: setup
+	cd .. && ./docs/_utils/doxygen.sh
+	poetry run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
+
+.PHONY: dirhtml
+dirhtml: setup
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml: setup
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: epub
+epub: 	setup
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:	setup
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: dummy
+dummy: 	setup
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."
+
+.PHONY: linkcheck
+linkcheck: setup
+	$(SPHINXBUILD) -b linkcheck . $(BUILDDIR)/linkcheck
+
+.PHONY: multiversion
+multiversion: setup
+	poetry run ./_utils/multiversion.sh
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

docs/_utils/api.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to API Documentation</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; URL=./api/classes.html">
+  </head>
+</html>

docs/_utils/deploy.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Clone repo
+git clone "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" --branch gh-pages --single-branch gh-pages
+cp -r docs/_build/dirhtml/* gh-pages
+# Redirections
+./docs/_utils/redirect.sh > gh-pages/index.html
+find  gh-pages/* -name "api.html" -exec cp ./docs/_utils/api.html {} \;
+# Deploy
+cd gh-pages
+touch .nojekyll
+git config --local user.email "[email protected]"
+git config --local user.name "GitHub Action"
+git add .
+git commit -m "Publish docs" || true
+git push origin gh-pages --force

docs/_utils/doxygen.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+GITHUB_VERSION=${GITHUB_REF##*/}
+
+OUTPUT_DIR="docs/_build/dirhtml/api"
+if [[ "$GITHUB_VERSION" != "" ]]; then
+    OUTPUT_DIR="docs/_build/dirhtml/$GITHUB_VERSION/api"
+    echo "HTML_OUTPUT = $OUTPUT_DIR" >> doxyfile
+fi
+echo $OUTPUT_DIR
+mkdir -p "$OUTPUT_DIR"
+doxygen doxyfile

docs/_utils/multiversion.sh

@@ -0,0 +1,3 @@
+#! /bin/bash
+
+cd .. && sphinx-multiversion docs/source docs/_build/dirhtml

docs/_utils/redirect.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+cat <<- _EOF_
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to Driver</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; URL=./${LATEST_VERSION}/index.html">
+    <link rel="canonical" href="./${LATEST_VERSION}/index.html">
+  </head>
+</html>
+_EOF_

docs/_utils/redirections.yaml

@@ -0,0 +1 @@
+api: /api/classes.html

docs/_utils/setup.sh

@@ -0,0 +1,16 @@
+#! /bin/bash
+
+if pwd | egrep -q '\s'; then
+	echo "Working directory name contains one or more spaces."
+	exit 1
+fi
+
+which python3 || { echo "Failed to find python3. Try installing Python for your operative system: https://www.python.org/downloads/" && exit 1; }
+# install pipx
+which pipx || python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+
+# install poetry
+which poetry || pipx install poetry
+poetry --version || { echo "Failed to find or install poetry. Try installing it manually: https://python-poetry.org/docs/#installation" && exit 1; }
+poetry install