pages/docs revamp

Author: mrbuche

.github/workflows/docs.sh

@@ -1,39 +1,34 @@
-name: pages
+name: Pages
 on:
   push:
-    branches: [ main ]
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
 jobs:
-  gh-pages:
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Install package and docs extras
-        run: pip install .[all]
-      - name: pylint badge
-        run: |
-          python -m pylint --disable=C0103 --output-format=text statmechcrack | tee pylint.log || pylint-exit $?
-          PYLINT_SCORE=$(sed -n 's/^Your code has been rated at \([-0-9.]*\)\/.*/\1/p' pylint.log)
-          if (( $(echo "${PYLINT_SCORE} >= 8.0" | bc -l) )); then
-            COLOR=brightgreen
-          elif (( $(echo "${PYLINT_SCORE} >= 4.0" | bc -l) )); then
-            COLOR=yellow
-          elif (( $(echo "${PYLINT_SCORE} >= 2.0" | bc -l) )); then
-            COLOR=orange
-          else
-            COLOR=red
-          fi
-          curl "https://img.shields.io/badge/Pylint-${PYLINT_SCORE}-${COLOR}?logo=python&logoColor=FBE072" -o pylint.svg
-      - name: Build docs
-        run: |
-          sudo apt-get install pandoc
-          source .github/workflows/docs.sh
-          sphinx-build -b html source/ build/html/
-          sed -i -e "s/ module</</g" build/html/*.html
-          sed -i '/Built with/,/Docs<\/a>./d' build/html/*.html
-          mv build/html/ ../public/
-          mv ../pylint.svg ../public/
-      - name: Deploy docs to gh-pages
-        uses: peaceiris/actions-gh-pages@v3
+      - uses: actions/checkout@v3
+      - uses: actions/configure-pages@v3
+      - uses: actions/jekyll-build-pages@v1
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: public/
+          source: ./pages/
+          destination: ./_site
+      - uses: actions/upload-pages-artifact@v1
+  deploy:
+    if: github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/pages.yml

@@ -1,13 +1,11 @@
 version: 2
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
-sphinx:
-   configuration: docs/source/conf.py
-python:
-   install:
-   - method: pip
-     path: .
-     extra_requirements:
-       - docs
+    python: "3.11"
+  commands:
+    - pip install .[docs]
+    - pip install -r docs/requirements.txt
+    - cd docs/ && make html
+    - mkdir _readthedocs/
+    - mv docs/build/html/ _readthedocs/

.github/workflows/rtd.yml

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.readthedocs.yaml

@@ -0,0 +1,14 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+{% block breadcrumbs_aside %}
+<li class="wy-breadcrumbs-aside">
+    <a style="text-decoration: none; padding: 0" href="https://github.com/sandialabs/statMechCrack">
+      <iconify-icon icon="fa-brands:github" height="1.6em"></iconify-icon>
+    </a>
+    <a style="text-decoration: none; padding: 0" href="https://pypi.org/project/statmechcrack">
+      <iconify-icon icon="simple-icons:pypi" height="1.6em"></iconify-icon>
+    </a>
+    <a style="text-decoration: none; padding: 0" href="https://anaconda.org/mrbuche/statmechcrack">
+      <iconify-icon icon="simple-icons:anaconda" height="1.6em"></iconify-icon>
+    </a>
+</li>
+{% endblock %}

README.rst

@@ -0,0 +1,19 @@
+{% extends "!footer.html" %}
+{%- block contentinfo %}
+{{ super }}
+<a href="http://sandia.gov/" rel="noopener noreferrer" target="_blank" style="text-decoration: none">
+    <img alt="Sandia National Laboratories" longdesc="http://sandia.gov" src="https://raw.githubusercontent.com/sandialabs/Polymers/main/pages/assets/images/SNL_Horizontal_Black_Blue.png" style="height:37px">
+</a>
+&nbsp;
+<a href="http://energy.gov" rel="noopener noreferrer" target="_blank" style="text-decoration: none">
+    <img alt="U.S. Department of Energy" longdesc="http://energy.gov" src="https://raw.githubusercontent.com/sandialabs/Polymers/main/pages/assets/images/New_DOE_Logo_Color.png" style="height:37px">
+</a>
+&nbsp;
+<a href="http://nnsa.energy.gov/" rel="noopener noreferrer" target="_blank" style="text-decoration: none">
+    <img alt="National Nuclear Security Administration" longdesc="http://nnsa.gov" src="https://raw.githubusercontent.com/sandialabs/Polymers/main/pages/assets/images/NNSA Logo_Color.png" style="height:37px">
+</a>
+<br><br>
+<div style="font-size: 0.8em">
+    Sandia National Laboratories is a multimission laboratory managed and operated by National Technology and Engineering Solutions of Sandia, LLC., a wholly owned subsidiary of Honeywell International, Inc., for the U.S. Department of Energy's National Nuclear Security Administration under contract DE-NA-0003525.
+</div>
+{% endblock %}

docs/Makefile

@@ -0,0 +1,5 @@
+{%- extends "sphinx_rtd_theme/layout.html" %}
+{%- block extrahead %}
+{{ super() }}
+<script src="https://code.iconify.design/iconify-icon/1.0.2/iconify-icon.min.js"></script>
+{% endblock %}

docs/_static/custom.css renamed to docs/source/_static/custom.css

@@ -24,28 +24,33 @@ def get_version():
     LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, \
     the U.S. Government retains certain rights in this software'
 
-templates_path = ['_templates']
-html_static_path = ['_static']
-html_css_files = ['custom.css']
-html_theme = 'sphinx_rtd_theme'
-html_theme_options = {'navigation_depth': 8}
+add_module_names = False
+bibtex_bibfiles = ['main.bib']
+bibtex_default_style = 'plain'
 extensions = [
-    'sphinx_copybutton',
+    'matplotlib.sphinxext.plot_directive',
+    'nbsphinx',
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
-    'matplotlib.sphinxext.plot_directive',
     'sphinxcontrib.bibtex',
-    'nbsphinx',
+    'sphinx_copybutton'
+]
+html_css_files = [
+    'custom.css'
 ]
 html_show_sphinx = False
+html_show_sourcelink = False
+html_static_path = ['_static']
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'navigation_depth': 8
+}
 latex_engine = 'xelatex'
-bibtex_bibfiles = ['main.bib']
-bibtex_default_style = 'plain'
+nbsphinx_allow_errors = True
 plot_html_show_formats = False
 plot_html_show_source_link = False
 plot_include_source = True
-add_module_names = False
 plot_rcparams = {'font.size': 10}
 plot_formats = [('png', 300)]
-nbsphinx_allow_errors = True
+templates_path = ['_templates']