MAINT: Enable doc generation

Enable doc generation
Add more to customization

.github/workflows/generate-documentation.yml

@@ -0,0 +1,60 @@
+name: Generate Documentation
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.8]
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - name: Event type
+      run: echo $EVENT_TYPE
+      env:
+        EVENT_TYPE: ${{ github.event_name }}
+    - name: Install pandoc
+      uses: r-lib/actions/setup-pandoc@v1
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip wheel setuptools
+        python -m pip install -r requirements.txt
+        python -m pip install -r docs/requirements.txt
+        python -m pip list
+    - name: Install sphinx-material
+      run: python -m pip install -e . --no-build-isolation -v
+    - name: Build documentation
+      run: |
+        pushd docs
+        O="-j auto" make html
+        popd
+    - name: Move and commit documentation
+      env:
+        GIT_TAG: ${{ github.event.release.tag_name }}
+      run: |
+        source tools/docbuild-commit.sh
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: gh-pages
+      if: ${{ github.event_name == 'release' || github.event_name == 'push' }}

docs/customization.rst

@@ -69,7 +69,12 @@ Configuration Options
    Minify css files found in the output directory.
 ``logo_icon``
    Set the logo icon. Should be a pre-escaped html string that indicates a
-   unicode point, e.g., ``'&#xe869'`` which is used on this site.
+   unicode point, e.g., ``'&#xe869'`` which is used on this site. The code
+   point refers to the `Material Icons <https://fonts.google.com/icons>`_ font.
+   This set provides a reasonable set of utility icons. Most sites should not
+   use ``logo_icon`` and instead should set ``html_logo`` in ``conf.py`` to
+   point to a custom SVG icon. Note that ``logo_icon`` takes precedent over
+   ``html_logo`` and so it should be left empty when using ``html_logo``.
 ``master_doc``
    Include the master document at the top of the page in the breadcrumb bar.
    You must also set this to true if you want to override the rootrellink block, in which

docs/index.rst

@@ -100,6 +100,7 @@ or ``theme.conf`` for more details.
     markdown.md
     rst-cheatsheet/rst-cheatsheet
     basics
+    titleless
 
 .. toctree::
     :caption: Changes and License

docs/titleless.rst

@@ -0,0 +1,33 @@
+.. rubric:: Titleless
+
+This page does not have a title.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam gravida dui eu erat tincidunt mollis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut porta, tortor nec suscipit vulputate, sapien dolor bibendum arcu, vel volutpat tortor ligula pellentesque arcu. Praesent rutrum lacus non dui imperdiet, vitae dignissim sem ultricies. Pellentesque hendrerit purus sed nulla ultricies, sit amet venenatis lacus sodales. Phasellus eget luctus dolor. Suspendisse diam diam, scelerisque ac ante at, volutpat hendrerit ipsum. Fusce consectetur, eros eu volutpat tincidunt, sem sem accumsan diam, sed mattis sem sem id turpis. Nullam consequat elit a posuere tempus. Quisque ultrices, arcu varius rutrum luctus, nisi sapien interdum erat, eu vestibulum enim orci quis purus. Pellentesque ut nunc vitae ex pretium mollis quis non diam. Aenean fermentum diam finibus, euismod sapien quis, viverra elit. Vivamus vel dolor quam.
+
+Vivamus neque velit, volutpat eget tortor in, porttitor porta felis. Cras mauris diam, viverra id orci venenatis, vehicula eleifend diam. In vehicula dui ac justo elementum, tristique finibus nisi laoreet. Morbi at aliquam eros, ac consectetur orci. Fusce venenatis, ligula nec finibus vehicula, dui lectus viverra dui, et porta ligula turpis in nulla. Donec ipsum diam, placerat in erat vitae, blandit lobortis orci. Phasellus velit augue, ornare nec est sit amet, dictum mollis sem. Etiam varius metus vel magna ultrices sagittis. Nullam id finibus purus. Donec pretium quis purus eu ullamcorper. Mauris ac cursus arcu. Aliquam tempus aliquet mauris, ac tincidunt diam imperdiet sed. Donec vestibulum posuere turpis non venenatis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras urna odio, varius et risus id, tristique maximus purus. Donec lectus magna, venenatis ac enim vitae, consectetur aliquam magna.
+
+Maecenas facilisis et dolor in molestie. Quisque consectetur dui eu eleifend condimentum. Sed aliquam accumsan metus, elementum sodales leo iaculis quis. Quisque venenatis sapien ac nibh pretium tincidunt. In blandit tellus libero, sed fermentum augue ultrices vel. Phasellus lectus mauris, molestie id lectus et, blandit malesuada risus. In pretium nisi pulvinar, tristique sem vitae, dignissim augue. Vivamus non metus condimentum, suscipit justo at, venenatis nulla. Donec hendrerit consequat efficitur.
+
+Aliquam erat volutpat. Quisque ligula eros, faucibus non pulvinar sed, euismod sed purus. Pellentesque pretium turpis at suscipit ornare. Nullam non nunc nec turpis vehicula porttitor quis vel velit. Nam hendrerit mi urna, ut finibus eros efficitur sit amet. Sed dictum, felis a ullamcorper tincidunt, metus libero tincidunt lectus, sed aliquam felis mi et nisi. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nulla eget hendrerit mi. Morbi semper lectus eu magna egestas molestie. In et libero sagittis, convallis dui ut, commodo sem.
+
+Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Praesent lacinia purus mauris, vehicula auctor dolor fringilla vel. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus faucibus lacus vel lacus hendrerit, et porttitor mi cursus. Curabitur nisl turpis, vehicula euismod mollis eu, sagittis id erat. Aenean tortor dolor, mollis porttitor dignissim nec, scelerisque id magna. Pellentesque bibendum quis nisi eget mollis. Sed purus lectus, hendrerit nec dolor ac, condimentum ornare velit. Praesent efficitur iaculis tempor. Curabitur convallis, quam ut luctus blandit, orci nunc tempor orci, ac vehicula est arcu in sapien. Quisque quam mi, sagittis quis finibus vulputate, commodo nec lorem.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam gravida dui eu erat tincidunt mollis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut porta, tortor nec suscipit vulputate, sapien dolor bibendum arcu, vel volutpat tortor ligula pellentesque arcu. Praesent rutrum lacus non dui imperdiet, vitae dignissim sem ultricies. Pellentesque hendrerit purus sed nulla ultricies, sit amet venenatis lacus sodales. Phasellus eget luctus dolor. Suspendisse diam diam, scelerisque ac ante at, volutpat hendrerit ipsum. Fusce consectetur, eros eu volutpat tincidunt, sem sem accumsan diam, sed mattis sem sem id turpis. Nullam consequat elit a posuere tempus. Quisque ultrices, arcu varius rutrum luctus, nisi sapien interdum erat, eu vestibulum enim orci quis purus. Pellentesque ut nunc vitae ex pretium mollis quis non diam. Aenean fermentum diam finibus, euismod sapien quis, viverra elit. Vivamus vel dolor quam.
+
+Vivamus neque velit, volutpat eget tortor in, porttitor porta felis. Cras mauris diam, viverra id orci venenatis, vehicula eleifend diam. In vehicula dui ac justo elementum, tristique finibus nisi laoreet. Morbi at aliquam eros, ac consectetur orci. Fusce venenatis, ligula nec finibus vehicula, dui lectus viverra dui, et porta ligula turpis in nulla. Donec ipsum diam, placerat in erat vitae, blandit lobortis orci. Phasellus velit augue, ornare nec est sit amet, dictum mollis sem. Etiam varius metus vel magna ultrices sagittis. Nullam id finibus purus. Donec pretium quis purus eu ullamcorper. Mauris ac cursus arcu. Aliquam tempus aliquet mauris, ac tincidunt diam imperdiet sed. Donec vestibulum posuere turpis non venenatis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras urna odio, varius et risus id, tristique maximus purus. Donec lectus magna, venenatis ac enim vitae, consectetur aliquam magna.
+
+Maecenas facilisis et dolor in molestie. Quisque consectetur dui eu eleifend condimentum. Sed aliquam accumsan metus, elementum sodales leo iaculis quis. Quisque venenatis sapien ac nibh pretium tincidunt. In blandit tellus libero, sed fermentum augue ultrices vel. Phasellus lectus mauris, molestie id lectus et, blandit malesuada risus. In pretium nisi pulvinar, tristique sem vitae, dignissim augue. Vivamus non metus condimentum, suscipit justo at, venenatis nulla. Donec hendrerit consequat efficitur.
+
+Aliquam erat volutpat. Quisque ligula eros, faucibus non pulvinar sed, euismod sed purus. Pellentesque pretium turpis at suscipit ornare. Nullam non nunc nec turpis vehicula porttitor quis vel velit. Nam hendrerit mi urna, ut finibus eros efficitur sit amet. Sed dictum, felis a ullamcorper tincidunt, metus libero tincidunt lectus, sed aliquam felis mi et nisi. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nulla eget hendrerit mi. Morbi semper lectus eu magna egestas molestie. In et libero sagittis, convallis dui ut, commodo sem.
+
+Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Praesent lacinia purus mauris, vehicula auctor dolor fringilla vel. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus faucibus lacus vel lacus hendrerit, et porttitor mi cursus. Curabitur nisl turpis, vehicula euismod mollis eu, sagittis id erat. Aenean tortor dolor, mollis porttitor dignissim nec, scelerisque id magna. Pellentesque bibendum quis nisi eget mollis. Sed purus lectus, hendrerit nec dolor ac, condimentum ornare velit. Praesent efficitur iaculis tempor. Curabitur convallis, quam ut luctus blandit, orci nunc tempor orci, ac vehicula est arcu in sapien. Quisque quam mi, sagittis quis finibus vulputate, commodo nec lorem.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam gravida dui eu erat tincidunt mollis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut porta, tortor nec suscipit vulputate, sapien dolor bibendum arcu, vel volutpat tortor ligula pellentesque arcu. Praesent rutrum lacus non dui imperdiet, vitae dignissim sem ultricies. Pellentesque hendrerit purus sed nulla ultricies, sit amet venenatis lacus sodales. Phasellus eget luctus dolor. Suspendisse diam diam, scelerisque ac ante at, volutpat hendrerit ipsum. Fusce consectetur, eros eu volutpat tincidunt, sem sem accumsan diam, sed mattis sem sem id turpis. Nullam consequat elit a posuere tempus. Quisque ultrices, arcu varius rutrum luctus, nisi sapien interdum erat, eu vestibulum enim orci quis purus. Pellentesque ut nunc vitae ex pretium mollis quis non diam. Aenean fermentum diam finibus, euismod sapien quis, viverra elit. Vivamus vel dolor quam.
+
+Vivamus neque velit, volutpat eget tortor in, porttitor porta felis. Cras mauris diam, viverra id orci venenatis, vehicula eleifend diam. In vehicula dui ac justo elementum, tristique finibus nisi laoreet. Morbi at aliquam eros, ac consectetur orci. Fusce venenatis, ligula nec finibus vehicula, dui lectus viverra dui, et porta ligula turpis in nulla. Donec ipsum diam, placerat in erat vitae, blandit lobortis orci. Phasellus velit augue, ornare nec est sit amet, dictum mollis sem. Etiam varius metus vel magna ultrices sagittis. Nullam id finibus purus. Donec pretium quis purus eu ullamcorper. Mauris ac cursus arcu. Aliquam tempus aliquet mauris, ac tincidunt diam imperdiet sed. Donec vestibulum posuere turpis non venenatis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras urna odio, varius et risus id, tristique maximus purus. Donec lectus magna, venenatis ac enim vitae, consectetur aliquam magna.
+
+Maecenas facilisis et dolor in molestie. Quisque consectetur dui eu eleifend condimentum. Sed aliquam accumsan metus, elementum sodales leo iaculis quis. Quisque venenatis sapien ac nibh pretium tincidunt. In blandit tellus libero, sed fermentum augue ultrices vel. Phasellus lectus mauris, molestie id lectus et, blandit malesuada risus. In pretium nisi pulvinar, tristique sem vitae, dignissim augue. Vivamus non metus condimentum, suscipit justo at, venenatis nulla. Donec hendrerit consequat efficitur.
+
+Aliquam erat volutpat. Quisque ligula eros, faucibus non pulvinar sed, euismod sed purus. Pellentesque pretium turpis at suscipit ornare. Nullam non nunc nec turpis vehicula porttitor quis vel velit. Nam hendrerit mi urna, ut finibus eros efficitur sit amet. Sed dictum, felis a ullamcorper tincidunt, metus libero tincidunt lectus, sed aliquam felis mi et nisi. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nulla eget hendrerit mi. Morbi semper lectus eu magna egestas molestie. In et libero sagittis, convallis dui ut, commodo sem.
+
+Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Praesent lacinia purus mauris, vehicula auctor dolor fringilla vel. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus faucibus lacus vel lacus hendrerit, et porttitor mi cursus. Curabitur nisl turpis, vehicula euismod mollis eu, sagittis id erat. Aenean tortor dolor, mollis porttitor dignissim nec, scelerisque id magna. Pellentesque bibendum quis nisi eget mollis. Sed purus lectus, hendrerit nec dolor ac, condimentum ornare velit. Praesent efficitur iaculis tempor. Curabitur convallis, quam ut luctus blandit, orci nunc tempor orci, ac vehicula est arcu in sapien. Quisque quam mi, sagittis quis finibus vulputate, commodo nec lorem.

tools/docbuild-commit.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+export GIT_REPO_DIR=${PWD}
+echo "Set git email and name"
+git config user.email "kevin.k.sheppard@gmail.com"
+git config user.name "Kevin Sheppard"
+git config advice.addIgnoredFile false
+echo "Checkout pages"
+git checkout gh-pages
+echo "Remove devel"
+rm -rf devel
+echo "Make a new devel"
+mkdir devel
+echo "Checking for tag"
+if [[ -n "${GIT_TAG}" ]]; then
+  echo "Tag ${GIT_TAG} is defined"
+  echo "Copy docs to root"
+  echo cp -r ${PWD}/docs/_build/html/* ${PWD}/
+  cp -r ${PWD}/docs/_build/html/* ${PWD}
+else
+  echo "Tag is ${GIT_TAG}. Not updating main documents"
+fi
+echo "Copy docs to devel"
+echo cp -r ${PWD}/docs/_build/html/* ${PWD}/devel/
+cp -r ${PWD}/docs/_build/html/* ${PWD}/devel/
+echo "Clean up docs"
+cd ${GIT_REPO_DIR}/docs
+make clean && git clean -xfd
+echo "Add files"
+cd ${GIT_REPO_DIR}
+git add .
+git add --all .
+git add -u .
+# Ensure key files are added
+git add devel/**/* || true
+git add **/*.html || true
+git add **/*.ipynb || true
+git add **/*.txt || true
+git add _images/* || true
+git add _sources/**/* || true
+git add _modules/**/* || true
+git add _static/**/* || true
+echo "Github Actions docs build after commit ${GITHUB_SHA::8}"
+git commit -a -m "Github Actions docs build after commit ${GITHUB_SHA::8}"