build & publish documentation to gh-pages from GitHub Actions workflow

.github/workflows/publish-sphinx.yml

@@ -0,0 +1,108 @@
+name: Publish Sphinx Docs to GitHub Pages
+on: [push]
+
+# see: https://sphinx-notes.github.io/pages/
+# see: https://github.com/marketplace/actions/sphinx-to-github-pages
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@master
+      with:
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+
+    - name: Install build requirements
+      run: |
+        pip install -r requirements.txt
+
+    - name: Diagnostic
+      run: |
+        pip list
+
+    - name: Run the test suite
+      run: |
+        # stops publishing when known problems are found
+        python utils/test_suite.py
+
+    - name: Prepare for out-of-source Sphinx build
+      run: |
+        rm -rf ./build
+        mkdir ./build
+        python ./utils/build_preparation.py . ./build
+
+    - name: Diagnostic
+      run: |
+        ls -lAFGh
+        ls -lAFGh ./build
+
+    - name: Install LaTeX
+      run: |
+        sudo apt-get update -y && \
+        sudo apt-get install -y \
+          latexmk \
+          texlive-latex-recommended \
+          texlive-latex-extra \
+          texlive-fonts-recommended
+
+    - name: Build impatient guide
+      run: |
+        make -C ./build/impatient-guide html latexpdf
+        ls -lAFGh ./build/impatient-guide/_build/latex/*.pdf
+
+        # Copy to documentation source directory
+        cp \
+          ./build/impatient-guide/_build/latex/NXImpatient.pdf \
+          ./build/manual/source/_static/
+
+    - name: Build PDF of manual
+      run: |
+        # expect next make (PDF) to fail (thus exit 0)
+        # since nexus.ind not found first time
+
+        # extra option for "levels nested too deeply" error
+        ( \
+          make latexpdf \
+            LATEXOPTS="--interaction=nonstopmode" \
+            -C build/manual \
+          || exit 0 \
+        )
+
+        # make that missing file
+        makeindex build/manual/build/latex/nexus.idx
+
+        # build the PDF, still a failure will be noted
+        # but we can ignore it without problem
+        ( \
+          make latexpdf \
+            LATEXOPTS="--interaction=nonstopmode" \
+            -C build/manual \
+          || exit 0\
+        )
+
+        # Copy to documentation source directory
+        cp \
+          ./build/manual/build/latex/nexus.pdf \
+          ./build/manual/source/_static/NeXusManual.pdf
+
+    - name: Include other PDFs
+      run: |
+        wget https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf -O ./build/manual/source/_static/NeXusIntern.pdf
+        wget https://github.com/nexusformat/code/raw/master/applications/NXtranslate/docs/NXtranslate.pdf -O ./build/manual/source/_static/NXtranslate.pdf
+
+    - name: Build (html) and Commit
+      uses: sphinx-notes/pages@master
+      with:
+        # path to conf.py directory
+        documentation_path: build/manual/source
+
+    - name: Publish if refs/tags
+      # remove/comment next line to push right away
+      if: startsWith(github.ref, 'refs/tags')
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: gh-pages

CHANGES.rst

@@ -14,6 +14,13 @@ Change History
 
 :v2021.10:  expected *2021-10*
 
+    * `#955 <https://github.com/nexusformat/definitions/issues/955>`_
+       Documentation built and published from GitHub Actions workflow
+
+    * `#951 <https://github.com/nexusformat/definitions/issues/951>`_
+       - drop support for Python <3.7 when building documentation & testing NXDL files
+       - included PDF file subdirectory changed from `pdf/` to `_static/`
+
     * `#884 <https://github.com/nexusformat/definitions/issues/884>`_
        switch repository default branch from master to main
 

impatient-guide/index.rst

@@ -15,7 +15,7 @@ Why NeXus?
    This document is available online in 
    `HTML <https://manual.nexusformat.org/impatient>`_
    and
-   `PDF <https://manual.nexusformat.org/pdf/NXImpatient.pdf>`_
+   `PDF <https://manual.nexusformat.org/_static/NXImpatient.pdf>`_
    formats.
 
 The NeXus data format [#NeXus]_ is a tool which has been designed to

jenkins_build

@@ -46,7 +46,7 @@ if test "${job_name}" = "main branch"; then
     rm -fr ${DIST_ROOT}/*
     [ -f /tmp/CNAME.$$ ] && mv /tmp/CNAME.$$ ${DIST_ROOT}/CNAME
 
-    mkdir ${DIST_ROOT}/pdf
+    # mkdir ${DIST_ROOT}/pdf
 
     cd manual
     cd source
@@ -69,9 +69,10 @@ if test "${job_name}" = "main branch"; then
     cd ..
 
     #pdf
-    cp -f latex/nexus.pdf ${DIST_ROOT}/pdf/NeXusManual.pdf
-    wget https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf -O ${DIST_ROOT}/pdf/NeXusIntern.pdf
-    wget https://github.com/nexusformat/code/raw/master/applications/NXtranslate/docs/NXtranslate.pdf -O ${DIST_ROOT}/pdf/NXtranslate.pdf
+    ( cd impatient-guide && cp -f _build/latex/NXImpatient.pdf ${DIST_ROOT}/_static/NXImpatient.pdf && cp -rf _build/html ${DIST_ROOT}/impatient )
+    cp -f latex/nexus.pdf ${DIST_ROOT}/_static/NeXusManual.pdf
+    wget https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf -O ${DIST_ROOT}/_static/NeXusIntern.pdf
+    wget https://github.com/nexusformat/code/raw/master/applications/NXtranslate/docs/NXtranslate.pdf -O ${DIST_ROOT}/_static/NXtranslate.pdf
 
     #html
     cp -fr html/* ${DIST_ROOT}
@@ -80,8 +81,6 @@ if test "${job_name}" = "main branch"; then
 
     cp -fr /isis/www/nexus/doxygen ${DIST_ROOT}
 
-    ( cd impatient-guide && cp -f _build/latex/NXImpatient.pdf ${DIST_ROOT}/pdf/NXImpatient.pdf && cp -rf _build/html ${DIST_ROOT}/impatient )
-
     cd ${DIST_ROOT}
     git add .
     git commit -m "Update docs for ${git_rev}"

manual/source/design.rst

@@ -409,7 +409,7 @@ a URL to a group in another file.  More information about the
 ``@napimount`` attribute is described in the
 *NeXus Programmers Reference*. [#]_
 
-.. [#] https://manual.nexusformat.org/pdf/NeXusIntern.pdf
+.. [#] https://manual.nexusformat.org/_static/NeXusIntern.pdf
 
 .. index:: link; external file, NeXus link
 

manual/source/index.rst

@@ -35,7 +35,7 @@ This manual built |today|.
    	https://manual.nexusformat.org/
 
    :PDF:
-   	https://manual.nexusformat.org/pdf/NeXusManual.pdf
+   	https://manual.nexusformat.org/_static/NeXusManual.pdf
 
    A very brief overview (title: *NeXus for the Impatient*) 
    is also available (separate from the manual).
@@ -44,7 +44,7 @@ This manual built |today|.
       https://manual.nexusformat.org/impatient/
 
    :PDF:
-      https://manual.nexusformat.org/pdf/NXImpatient.pdf
+      https://manual.nexusformat.org/_static/NXImpatient.pdf
 
 ..  Suggestions for adding to this manual:
 

manual/source/introduction-napi.rst

@@ -26,7 +26,7 @@ in the :ref:`NAPI <NAPI>` chapter and may be downloaded
 from the NeXus development site. [#]_
 
 For an even more detailed description of the internal workings of NAPI
-see the `NeXus Internals manual <https://manual.nexusformat.org/pdf/NeXusIntern.pdf>`_, copied from the NeXus code repository.
+see the `NeXus Internals manual <https://manual.nexusformat.org/_static/NeXusIntern.pdf>`_, copied from the NeXus code repository.
 That document is written for programmers who want to work on the NAPI itself.
 If you are new to NeXus and just want to implement basic file reading or writing
 you should not start by reading that.

nxdl.xsd

@@ -1076,7 +1076,7 @@
 							Group attribute that provides a URL to a group in another file.
 							More information is described in the *NeXus Programmers Reference*.
 
-							http://manual.nexusformat.org/pdf/NeXusIntern.pdf
+							http://manual.nexusformat.org/_static/NeXusIntern.pdf
 						</xs:documentation>
 					</xs:annotation>
 				</xs:attribute>