Merge pull request #12 from deeprob-org/issue-#10

PR for Issue #10

.github/workflows/sphinx-multidoc.yml

@@ -0,0 +1,48 @@
+# This is a workflow for pushing versioned documentation to the gh-pages branch
+name: Sphinx-MultiDoc
+
+on:
+  # Permits manual workflow dispatch
+  workflow_dispatch:
+
+  # Triggers the workflow on push events on the main branch and tags
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Checks-out your repository, so your job can access it
+      - uses: actions/checkout@v2
+
+      # Setup a Python environment
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+          architecture: 'x64'
+
+      # Install dependencies
+      - name: Install Dependencies
+        working-directory: docs
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
+
+      # Build versioned documentation
+      - name: Build Versioned Documentation
+        working-directory: docs
+        run: make
+
+      # Deploy versioned documentation, using GitHub Pages
+      - name: Deploy Documentation
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          force_orphan: true
+          enable_jekyll: false
+          publish_dir: docs/_build
+          github_token: ${{ secrets.GITHUB_TOKEN }}

docs/.gitignore

@@ -1,2 +1,2 @@
-api
 _build
+

docs/Makefile

@@ -1,21 +1,16 @@
-SPHINX_BUILD      = sphinx-build
-SPHINX_APIDOC     = sphinx-apidoc
+SPHINX_BUILD      = sphinx-multiversion
 SPHINX_BUILD_DIR  = _build
 SPHINX_SOURCE_DIR = .
-SPHINX_API_DIR    = api
-API_SOURCE_DIR    = ../deeprob
+SPHINX_INDEX_FILE = index.html
 
 .PHONY: clean
 
 # Make the HTML static site
-sphinx_html: sphinx_api
-	$(SPHINX_BUILD) -M html $(SPHINX_SOURCE_DIR) $(SPHINX_BUILD_DIR)
-
-# Make the API pages
-sphinx_api:
-	$(SPHINX_APIDOC) -o $(SPHINX_API_DIR) $(API_SOURCE_DIR)
+sphinx_html:
+	$(SPHINX_BUILD) $(SPHINX_SOURCE_DIR) $(SPHINX_BUILD_DIR)
+	cp $(SPHINX_SOURCE_DIR)/$(SPHINX_INDEX_FILE) $(SPHINX_BUILD_DIR)
 
 # Clean directories
 clean:
-	rm -rf $(SPHINX_API_DIR)
 	rm -rf $(SPHINX_BUILD_DIR)
+

docs/README.md

@@ -1,19 +1,26 @@
 ## Documentation
 
+The source code documentation is hosted using GitHub Pages at
+[deeprob-org.github.io/deeprob-kit](https://deeprob-org.github.io/deeprob-kit/).
+
 The documentation is generated automatically by Sphinx, using sources stored in the `docs` directory
 (with a slightly modified [*Read-the-Docs*](https://readthedocs.org/) theme).
-Sooner or later we will make it available also online, probably hosted using GitHub pages. 
+In particular, the documentation is versioned, i.e. there is a documentation page for the main branch and for every tag
+(or release) of the library.
+
+If you wish to build the documentation yourself, you will need to install the dependencies listed in `requirements.txt`.
+Moreover, in order to build versioned documentation, it is necessary to install a
+[fork of sphinx-multiversion](https://github.com/Holzhaus/sphinx-multiversion/pull/62) as following:
+```shell
+pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
+```
 
-If you wish to build the documentation yourself, you will need to install the dependencies listed in `requirements.txt`
-and execute the Makefile script as following:
-```bash
+Finally, it's possible to execute the Makefile script as following:
+```shell
 # Clean existing documentation (optional)
 make clean
-
-# Build source code API documentation
-make sphinx_api
-
 # Build HTML documentation
-make sphinx_html
+make
 ```
-The output HTML documentation can be found inside `_build/html` directory.
+The output HTML documentation, for any local branch and tag (or release), can be found inside the `_build`
+directory.

docs/_templates/versions.html

@@ -0,0 +1,25 @@
+<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">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>

docs/conf.py

@@ -7,24 +7,28 @@
 author = 'Lorenzo Loconte, Gennaro Gala'
 copyright = '2021, {}'.format(author)
 release = version = '1.0.0'
+sourcelib = 'deeprob'
 
 # -- General configuration ---------------------------------------------------
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.githubpages',
     'sphinx.ext.viewcode',
+    'sphinx_multiversion',
     'myst_parser',
     'sphinx_rtd_theme'
 ]
 source_suffix = ['.rst', '.md']
 exclude_patterns = ['api/modules.rst', 'README.md']
 
 # -- Options for HTML output -------------------------------------------------
+templates_path = ['_templates']
+html_sidebars = {'**': ['versions.html']}
 html_static_path = ['_static']
 html_theme = 'sphinx_rtd_theme'
 html_theme_options = {
-    'display_version': True,
+    'display_version': False,
     'navigation_depth': 6,
     'collapse_navigation': True,
 }
@@ -42,4 +46,11 @@
 }
 
 # -- MyST settings -----------------------------------------------------------
-suppress_warnings = ["myst.header"]
+suppress_warnings = ['myst.header']
+
+# -- Multiversion settings ---------------------------------------------------
+smv_tag_whitelist = r'^.*$'
+smv_branch_whitelist = r'^.*$'
+
+# Build API documentation using Sphinx APIdoc, for every version
+smv_prebuild_command = "sphinx-apidoc -o api '../{}'".format(sourcelib)

docs/index.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <title>Redirecting to https://deeprob-org.github.io/deeprob-kit/main</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; URL=https://deeprob-org.github.io/deeprob-kit/main/index.html">
+    <link rel="canonical" href="https://deeprob-org.github.io/deeprob-kit/main/index.html">
+  </head>
+</html>