docs: generate docs site with Sphinx

The result is easier to read than the individual .md files.

.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish
+
+on:
+  push:
+    branches:
+        - devel
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r docs/requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make html
+    - name: Deploy the docs
+      run: |
+        mkdir $HOME/output
+        mv _output/html $HOME/output/latest
+        touch $HOME/output/.nojekyll
+        mv docs/html/index2.html $HOME/output/index.html
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/intelkevinputnam/pmem-csi.git HEAD:gh-pages

.gitignore

@@ -1,3 +1,7 @@
 /vendor
 /_output
 /_work
+/.tox
+Manifest
+/_build
+

Jenkinsfile

@@ -171,7 +171,8 @@ pipeline {
 
                     // Install additional tools:
                     // - ssh client for govm
-                    sh "docker exec ${env.BUILD_CONTAINER} swupd bundle-add openssh-client"
+                    // - python3 for Sphinx (i.e. make html)
+                    sh "docker exec ${env.BUILD_CONTAINER} swupd bundle-add openssh-client python3-basic"
 
                     // Now commit those changes to ensure that the result of "swupd bundle add" gets cached.
                     sh "docker commit ${env.BUILD_CONTAINER} ${env.BUILD_IMAGE}"
@@ -213,6 +214,13 @@ pipeline {
             }
         }
 
+        stage('docsite') {
+            steps {
+                sh "${RunInBuilder()} ${env.BUILD_CONTAINER} make vhtml"
+                publishHTML([allowMissing: false, alwaysLinkToLastBuild: false, keepAll: false, reportDir: '_output/html', reportFiles: 'index.html', reportName: 'Doc Site', reportTitles: ''])
+            }
+        }
+
         stage('make test') {
             options {
                 timeout(time: 20, unit: "MINUTES")

Makefile

@@ -209,3 +209,28 @@ $(addprefix test-kustomize-,$(KUSTOMIZE_OUTPUT)): test-kustomize-%: _work/kustom
 .PHONY: check-go-version-%
 check-go-version-%:
 	@ hack/verify-go-version.sh "$*"
+
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _output
+
+# Generate doc site under _build/html with Sphinx.
+vhtml: _work/venv/.stamp
+	. _work/venv/bin/activate && \
+		$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) && \
+		cp docs/html/index.html $(BUILDDIR)/html/index.html
+
+html:
+		$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) && \
+		cp docs/html/index.html $(BUILDDIR)/html/index.html
+
+clean-html:
+	rm -rf _output/html
+
+# Set up a Python3 environment with the necessary tools for document creation.
+_work/venv/.stamp: docs/requirements.txt
+	rm -rf ${@D}
+	python3 -m venv ${@D}
+	. ${@D}/bin/activate && pip install -r $<
+	touch $@