Issue 147: add documentation versioning

.ci/install.sh

@@ -4,17 +4,20 @@
 if [ "$1" = "2" ]; then
     echo "install python-pninexus"
     docker exec --user root ndts chown -R tango:tango .
+    docker exec ndts python setup.py build
+    if [ "$?" != "0" ]; then exit 255; fi
     docker exec  --user root ndts python setup.py install
+    if [ "$?" != "0" ]; then exit 255; fi
     echo "build python3-pninexus docs"
-    docker exec  --user root ndts python setup.py  build_sphinx
+    docker exec ndts python setup.py  build_sphinx
 else
     echo "install python3-pninexus"
     docker exec  --user root ndts chown -R tango:tango .
+    docker exec ndts python3 setup.py build
+    if [ "$?" != "0" ]; then exit 255; fi
     docker exec  --user root ndts python3 setup.py install
+    if [ "$?" != "0" ]; then exit 255; fi
     echo "build python3-pninexus docs"
-    docker exec  --user root ndts python3 setup.py  build_sphinx
-fi
-if [ $? -ne "0" ]
-then
-    exit -1
+    docker exec ndts python3 setup.py  build_sphinx
 fi
+if [ "$?" != "0" ]; then exit 255; fi

.ci/run.sh

@@ -9,7 +9,4 @@ else
     docker exec --user root ndts python3 setup.py test
     # docker exec -it ndts python3 setup.py test
 fi
-if [ $? -ne "0" ]
-then
-    exit -1
-fi
+if [ "$?" != "0" ]; then exit 255; fi

.github/workflows/tests.yml

@@ -28,20 +28,63 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - name: Update bash files
-        run: |
-          chmod +x .ci/run.sh
-          chmod +x .ci/install.sh
+
       - name: Build the docker
         env:
           OS: ${{ matrix.os }}
         run: docker build -t ndts .ci/${OS}_py3
+
       - name: Run the docker
         run: docker run --name  ndts -d -it -v `pwd`:/home/tango  ndts
+
       - name: install python-pninexus
         run: .ci/install.sh 3
+
       - name: run tests
         run: .ci/run.sh 3
+
+      - name: Append documentation for the latest release version
+        if: github.ref == 'refs/heads/develop' &&  matrix.os == 'debian11'
+        run: |
+             docker  exec ndts /bin/bash -c "cp doc/index.html doc/_config.yml build"
+             docker  exec ndts /bin/bash -c "git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'"
+             docker  exec ndts /bin/bash -c "git fetch && git checkout gh-pages && git pull"
+             docker  exec ndts /bin/bash -c "mkdir -p ./latest && shopt -u dotglob && rm -rf ./latest/*"
+             docker  exec ndts /bin/bash -c "mv -f build/sphinx/html/* ./latest/"
+             docker  exec ndts /bin/bash -c "mv -f build/index.html build/_config.yml ."
+             # docker  exec ndts /bin/bash -c "mv -f build/devel ./latest/api/doxygen"
+             docker  exec ndts /bin/bash -c "rm -rf ./latest/_sources"
+             docker  exec --user root ndts /bin/bash -c "rm -rf build build_tools *.h5 src test"
+
+      - name: Extract the code version from the branch name
+        if: startsWith(github.ref, 'refs/heads/docs_') && matrix.os == 'debian11'
+        shell: bash
+        run: echo "##[set-output name=docver;]$(echo ${GITHUB_REF#refs/heads/docs_})"
+        id: extract_docver
+
+      - name: Append documentation for the extracted release version
+        if: startsWith(github.ref, 'refs/heads/docs_') &&  matrix.os == 'debian11'
+        run: |
+             echo Version: ${{ steps.extract_docver.outputs.docver }}
+             docker  exec ndts /bin/bash -c "git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'"
+             docker  exec ndts /bin/bash -c "git fetch && git checkout gh-pages && git pull"
+             docker  exec ndts /bin/bash -c "mkdir -p ./${{ steps.extract_docver.outputs.docver }}"
+             docker  exec ndts /bin/bash -c "shopt -u dotglob && rm -rf ./${{ steps.extract_docver.outputs.docver }}/* "
+             docker  exec ndts /bin/bash -c "mv -f build/sphinx/html/* ./${{ steps.extract_docver.outputs.docver }}/"
+             # docker  exec ndts /bin/bash -c "mv -f build/devel ./${{ steps.extract_docver.outputs.docver }}/api/doxygen"
+             docker  exec ndts /bin/bash -c "rm -rf ./${{ steps.extract_docver.outputs.docver }}/_sources"
+             docker  exec  --user root  ndts /bin/bash -c "rm -rf build build_tools *.h5 src test"
+
+      - name: Deploy documentation
+        if: (github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/docs_'))  &&  matrix.os == 'debian11'
+        uses: s0/git-publish-subdir-action@develop
+        env:
+          REPO: self
+          BRANCH: gh-pages
+          FOLDER: .
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MESSAGE: "Build: ({sha}) {msg}"
+
       - name: Stop the docker
         run: docker container stop ndts
 
@@ -53,19 +96,20 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - name: Update bash files
-        run: |
-          chmod +x .ci/run.sh
-          chmod +x .ci/install.sh
+
       - name: Build the docker
         env:
           OS: ${{ matrix.os }}
         run: docker build -t ndts .ci/${OS}_py2
+
       - name: Run the docker
         run: docker run --name  ndts -d -it -v `pwd`:/home/tango  ndts
+
       - name: install python-pninexus
         run: .ci/install.sh 2
+
       - name: run tests
         run: .ci/run.sh 2
+
       - name: Stop the docker
         run: docker container stop ndts

doc/_config.yml

@@ -0,0 +1,6 @@
+# Site settings
+title: python-pni
+email: jan.kotanski@desy.de
+description: "python-pni"
+
+include: ['_sources', '_static', '_images', 'nexus', 'h5cpp']

doc/index.html

@@ -0,0 +1,10 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+    <head>
+        <meta charset="UTF-8">
+        <meta http-equiv="refresh" content="0; url=stable/index.html">
+        <script type="text/javascript"> window.location.href = "stable/index.html" </script>
+        <title> Page Redirection </title>
+    </head>
+    <body>If you are not redirected automatically, follow this <a href='stable/index.html'>link to v:stable</a>.</body>
+</html>

doc/sphinx/_templates/versions.html

@@ -0,0 +1,14 @@
+<p>
+  <h3 class='versions'>{{ ('Versions') }}</h3>
+  <p>
+    <ul>
+      <li><a class="reference external" href="{{ pathto(master_doc, 1)|e }}/../../latest/index.html">v:latest</a></li>
+      <li><a class="reference external" href="{{ pathto(master_doc, 1)|e }}/../../stable/index.html">v:stable</a></li>
+      {% if docs_versions %}
+      {%- for ver in docs_versions %}
+      <li><a class="reference external" href="{{ pathto(master_doc, 1)|e }}/../../{{ ver }}/index.html">{{ ver }}</a></li>
+      {%- endfor %}
+      {% endif %}
+    </ul>
+  </p>
+</p>

doc/sphinx/conf.py

@@ -148,7 +148,19 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'localtoc.html',
+        'relations.html',
+	'searchbox.html',
+        # located at _templates/
+        'versions.html',
+    ]
+}
+
+html_context = {
+    "docs_versions" : ["v2.0.0", "v1.3.4"]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/sphinx/installation.rst

@@ -62,7 +62,6 @@ keyring
 
    $ curl -s http://repos.pni-hdri.de/debian_repo.pub.gpg  | gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/debian-hdri-repo.gpg --import
    $ chmod 644 /etc/apt/trusted.gpg.d/debian-hdri-repo.gpg
-1
 
 The return value of this command line should be `OK`.
 In a next step you have to add new package sources to your system. For this

setup.py

@@ -16,7 +16,14 @@
 cmdclass = {'build_sphinx': BuildDoc}
 name = "pninexus"
 version = "2.0.0"
-release = "2.0.0"
+# release = "2.0.0"
+release = "2.0"
+
+
+if release.count(".") == 1:
+    docs_release = '(latest)'
+else:
+    docs_release = release
 
 
 def get_build_dir():
@@ -230,7 +237,7 @@ def run(self):
         'build_sphinx': {
             'project': ('setup.py', name),
             'version': ('setup.py', version),
-            'release': ('setup.py', release)
+            'release': ('setup.py', docs_release)
         }
     }
 )