Merge pull request #1 from ScriptAutomate/furo-theme

Have new projects use the Furo theme for Sphinx, and update pre-commit job versions
saltstack · Aug 11, 2021 · 17b4565 · 17b4565
2 parents 0e4756c + 7b37765
commit 17b4565
Show file tree

Hide file tree

Showing 6 changed files with 92 additions and 102 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -2,7 +2,7 @@
 minimum_pre_commit_version: 2.4.0
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.5.0
+    rev: v4.0.1
     hooks:
       - id: check-merge-conflict  # Check for files that contain merge conflict strings.
       - id: trailing-whitespace
@@ -19,34 +19,34 @@ repos:
 # ----- Code Formatting ------------------------------------------------------------------------->
 
   - repo: https://github.com/saltstack/pre-commit-remove-import-headers
-    rev: 1.0.0
+    rev: 1.1.0
     hooks:
       - id: remove-import-headers
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.7.2
+    rev: v2.23.3
     hooks:
       - id: pyupgrade
         name: Rewrite Code to be Py3.6+
         args: [--py36-plus]
 
   - repo: https://github.com/asottile/reorder_python_imports
-    rev: v2.3.5
+    rev: v2.6.0
     hooks:
       - id: reorder-python-imports
         args: [--py36-plus]
 
   - repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 21.7b0
     hooks:
       - id: black
         args: []
 
   - repo: https://github.com/asottile/blacken-docs
-    rev: v1.7.0
+    rev: v1.10.0
     hooks:
       - id: blacken-docs
-        additional_dependencies: [black==20.8b1]
+        additional_dependencies: [black==21.7b0]
 # <---- Code Formatting --------------------------------------------------------------------------
 
 # ----- Static Code Analysis -------------------------------------------------------------------->
@@ -67,7 +67,7 @@ repos:
 # ----- Static Requirements --------------------------------------------------------------------->
   # ----- Testing Static Requirements ----------------------------------------------------------->
   - repo: https://github.com/saltstack/pip-tools-compile-impersonate
-    rev: dff9089c1003af49665064067ff63c75b9b69dcd
+    rev: '4.1'
     hooks:
       - id: pip-tools-compile
         alias: compile-3.6-test-requirements

diff --git a/src/saltext/cli/project/.pre-commit-config.yaml.j2 b/src/saltext/cli/project/.pre-commit-config.yaml.j2
@@ -1,8 +1,8 @@
 ---
-minimum_pre_commit_version: 1.15.2
+minimum_pre_commit_version: 2.4.0
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.1.0
+    rev: v4.0.1
     hooks:
       - id: check-merge-conflict  # Check for files that contain merge conflict strings.
       - id: trailing-whitespace   # Trims trailing whitespace.
@@ -37,7 +37,7 @@ repos:
 
   - repo: https://github.com/s0undt3ch/salt-rewrite
     # Automatically rewrite code with known rules
-    rev: 1.3.2
+    rev: 1.3.3
     hooks:
       - id: salt-rewrite
         alias: rewrite-docstrings
@@ -47,7 +47,7 @@ repos:
 
   - repo: https://github.com/s0undt3ch/salt-rewrite
     # Automatically rewrite code with known rules
-    rev: 1.3.2
+    rev: 1.3.3
     hooks:
       - id: salt-rewrite
         alias: rewrite-tests
@@ -56,17 +56,17 @@ repos:
         args: [--silent, -E, fix_docstrings]
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.10.0
+    rev: v2.23.3
     hooks:
       - id: pyupgrade
-        name: Rewrite Code to be Py3.5+
+        name: Rewrite Code to be Py3.6+
         args: [
-          --py3-plus
+          --py36-plus
         ]
         exclude: src/saltext/{{ package_name }}/version.py
 
   - repo: https://github.com/asottile/reorder_python_imports
-    rev: v2.4.0
+    rev: v2.6.0
     hooks:
       - id: reorder-python-imports
         args: [
@@ -75,7 +75,7 @@ repos:
         exclude: src/saltext/{{ package_name }}/version.py
 
   - repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 21.7b0
     hooks:
       - id: black
         args: [-l 100]
@@ -87,7 +87,7 @@ repos:
       - id: blacken-docs
         args: [--skip-errors]
         files: ^(docs/.*\.rst|src/saltext/{{ package_name }}/.*\.py)$
-        additional_dependencies: [black==20.8b1]
+        additional_dependencies: [black==21.7b0]
   # <---- Formatting -----------------------------------------------------------------------------
 
   # ----- Security ------------------------------------------------------------------------------>
@@ -111,7 +111,7 @@ repos:
 
   # ----- Code Analysis ------------------------------------------------------------------------->
   - repo: https://github.com/saltstack/mirrors-nox
-    rev: v2020.8.22
+    rev: v2021.6.12
     hooks:
       - id: nox
         alias: lint-src
@@ -123,7 +123,7 @@ repos:
           - --
 
   - repo: https://github.com/saltstack/mirrors-nox
-    rev: v2020.8.22
+    rev: v2021.6.12
     hooks:
       - id: nox
         alias: lint-tests
@@ -137,19 +137,8 @@ repos:
 
   # ----- Static Test Requirements -------------------------------------------------------------->
   - repo: https://github.com/saltstack/pip-tools-compile-impersonate
-    rev: dff9089c1003af49665064067ff63c75b9b69dcd
+    rev: '4.1'
     hooks:
-      - id: pip-tools-compile
-        alias: compile-3.5-test-requirements
-        name: Py3.5 Test Requirements
-        files: ^requirements/tests.in$
-        pass_filenames: false
-        args:
-          - -v
-          - --py-version=3.5
-          - --platform=linux
-          - requirements/tests.in
-
       - id: pip-tools-compile
         alias: compile-3.6-test-requirements
         name: Py3.6 Test Requirements
@@ -196,17 +185,6 @@ repos:
   # <---- Static Test Requirements ---------------------------------------------------------------
 
   # ----- Static Lint Requirements -------------------------------------------------------------->
-      - id: pip-tools-compile
-        alias: compile-3.5-test-requirements
-        name: Py3.5 Lint Requirements
-        files: ^requirements/lint.in$
-        pass_filenames: false
-        args:
-          - -v
-          - --py-version=3.5
-          - --platform=linux
-          - requirements/lint.in
-
       - id: pip-tools-compile
         alias: compile-3.6-test-requirements
         name: Py3.6 Lint Requirements
@@ -253,17 +231,6 @@ repos:
   # <---- Static Lint Requirements ---------------------------------------------------------------
 
   # ----- Static Docs Requirements -------------------------------------------------------------->
-      - id: pip-tools-compile
-        alias: compile-3.5-test-requirements
-        name: Py3.5 Docs Requirements
-        files: ^requirements/docs.in$
-        pass_filenames: false
-        args:
-          - -v
-          - --py-version=3.5
-          - --platform=linux
-          - requirements/docs.in
-
       - id: pip-tools-compile
         alias: compile-3.6-test-requirements
         name: Py3.6 Docs Requirements

diff --git a/src/saltext/cli/project/docs/all.rst.j2 b/src/saltext/cli/project/docs/all.rst.j2
@@ -9,10 +9,10 @@
 .. toctree::
    :maxdepth: 2
 
-   ref/modules/all.rst
+   ref/modules.rst
 
 
 .. toctree::
    :maxdepth: 2
 
-   ref/states/all.rst
+   ref/states.rst
diff --git a/src/saltext/cli/project/docs/conf.py.j2 b/src/saltext/cli/project/docs/conf.py.j2
@@ -17,7 +17,6 @@ try:
 except ImportError:
     from importlib.metadata import distribution
 
-import sphinx_material_saltstack
 
 try:
     docs_basepath = os.path.abspath(os.path.dirname(__file__))
@@ -39,10 +38,10 @@ dist = distribution("saltext.{{ project_name }}")
 
 # -- Project information -----------------------------------------------------
 this_year = datetime.datetime.today().year
-if this_year == 2020:
-    copyright_year = 2020
+if this_year == 2021:
+    copyright_year = 2021
 else:
-    copyright_year = "2020 - {}".format(this_year)
+    copyright_year = "2021 - {}".format(this_year)
 project = dist.metadata["Summary"]
 author = dist.metadata["Author"]
 copyright = "{}, {}".format(copyright_year, author)
@@ -67,14 +66,15 @@ rst_prolog = """
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx_material_saltstack",
+    "furo",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
+    "sphinx_copybutton",
     "sphinxcontrib.spelling",
 ]
 
@@ -103,31 +103,8 @@ autosummary_generate = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_material_saltstack"
-html_theme_path = sphinx_material_saltstack.html_theme_path()
-html_context = sphinx_material_saltstack.get_html_context()
-html_sidebars = {"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]}
-html_theme_options = {
-    # Set the name of the project to appear in the navigation.
-    "nav_title": dist.metadata["Summary"],
-    # Set you GA account ID to enable tracking
-    # "google_analytics_account": "",
-    # Set the repo location to get a badge with stats (only if public repo)
-    "repo_url": dist.metadata["Project-Url"].split(", ")[-1],
-    "repo_name": dist.metadata["Name"],
-    "repo_type": "github" if "github" in dist.metadata["Project-Url"] else None,
-    # Visible levels of the global TOC; -1 means unlimited
-    "globaltoc_depth": 1,
-    # If False, expand all TOC entries
-    "globaltoc_collapse": False,
-    # If True, show hidden TOC entries
-    "globaltoc_includehidden": True,
-    # hide tabs?
-    "master_doc": False,
-    # Minify for smaller HTML/CSS assets
-    "html_minify": True,
-    "css_minify": True,
-}
+html_theme = "furo"
+html_title = project
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -136,25 +113,13 @@ html_static_path = ["_static"]
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = os.path.join(
-    html_theme_path[0],
-    "sphinx_material_saltstack",
-    "static",
-    "images",
-    "saltstack-logo.png",
-)
+html_logo = ''
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large. Favicons can be up to at least 228x228. PNG
 # format is supported as well, not just .ico'
-html_favicon = os.path.join(
-    html_theme_path[0],
-    "sphinx_material_saltstack",
-    "static",
-    "images",
-    "favicon.png",
-)
+html_favicon = ''
 
 # Sphinx Napoleon Config
 napoleon_google_docstring = True

diff --git a/src/saltext/cli/project/noxfile.py.j2 b/src/saltext/cli/project/noxfile.py.j2
@@ -7,6 +7,8 @@ import shutil
 import sys
 import tempfile
 
+from pathlib import Path
+
 import nox
 from nox.command import CommandFailed
 from nox.virtualenv import VirtualEnv
@@ -410,6 +412,60 @@ def docs(session):
     os.chdir(str(REPO_ROOT))
 
 
+@nox.session(name="docs-html", python="3")
+@nox.parametrize("clean", [False, True])
+@nox.parametrize("include_api_docs", [False, True])
+def docs_html(session, clean, include_api_docs):
+    """
+    Build Sphinx HTML Documentation
+
+    TODO: Add option for `make linkcheck` and `make coverage`
+          calls via Sphinx. Ran into problems with two when
+          using Furo theme and latest Sphinx.
+    """
+    _install_requirements(
+        session,
+        install_coverage_requirements=False,
+        install_test_requirements=False,
+        install_source=True,
+        install_extras=["docs"],
+    )
+    if include_api_docs:
+        gen_api_docs(session)
+    build_dir = Path("docs", "_build", "html")
+    sphinxopts = "-Wn"
+    if clean:
+        sphinxopts += "E"
+    args = [sphinxopts, "--keep-going", "docs", str(build_dir)]
+    session.run("sphinx-build", *args, external=True)
+
+
+@nox.session(name="docs-dev", python="3")
+@nox.parametrize("clean", [False, True])
+def docs_dev(session, clean) -> None:
+    """
+    Build and serve the Sphinx HTML documentation, with live reloading on file changes, via sphinx-autobuild.
+
+    Note: Only use this in INTERACTIVE DEVELOPMENT MODE. This SHOULD NOT be called
+        in CI/CD pipelines, as it will hang.
+    """
+    _install_requirements(
+        session,
+        install_coverage_requirements=False,
+        install_test_requirements=False,
+        install_source=True,
+        install_extras=["docs", "docsauto"],
+    )
+
+    # Launching LIVE reloading Sphinx session
+    build_dir = Path("docs", "_build", "html")
+    args = ["--watch", ".", "--open-browser", "docs", str(build_dir)]
+    if clean and build_dir.exists():
+        shutil.rmtree(build_dir)
+
+    session.run("sphinx-autobuild", *args)
+
+
 @nox.session(name="docs-crosslink-info", python="3")
 def docs_crosslink_info(session):
     """