Docs automation

Author: dgarcia360

.github/workflows/pages.yml

@@ -0,0 +1,34 @@
+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: Deploy
+      run : ./docs/_utils/deploy.sh
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        LATEST_VERSION: latest

.gitignore

@@ -4,8 +4,10 @@ testing/
 .settings
 .classpath
 .project
-doc
-docs
+docs/_build
+docs/_source
+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.

changelog/README.md

@@ -0,0 +1,76 @@
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = poetry run sphinx-build
+PAPER         =
+BUILDDIR      = _build
+SOURCE_DIR    = _source
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR)
+# 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
+	cp -Tr source $(SOURCE_DIR)
+	cd $(SOURCE_DIR) && find -name README.md -execdir mv '{}' index.md ';'
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf $(SOURCE_DIR)/*
+
+.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.yaml

@@ -0,0 +1,15 @@
+#!/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
+# Deploy
+cd gh-pages
+touch .nojekyll
+git config --local user.email "action@scylladb.com"
+git config --local user.name "GitHub Action"
+git add .
+git commit -m "Publish docs" || true
+git push origin gh-pages --force

docs/Makefile

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

docs/_utils/deploy.sh

@@ -0,0 +1,5 @@
+#! /bin/bash	
+
+cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
+    --pre-build './docs/_utils/doxygen.sh' \
+    --pre-build "find docs/source -name README.md -execdir mv '{}' index.md ';'"

docs/_utils/doxygen.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_