Merge pull request #21 from ScriptAutomate/sitevars-autoupdate

Use sitevars, nox, and json to update versions

Author: ScriptAutomate

.devcontainer.json

@@ -3,7 +3,7 @@
 {
 	"name": "Salt Install Guide",
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-	"image": "mcr.microsoft.com/devcontainers/python:0-3.10-bullseye",
+	"image": "mcr.microsoft.com/devcontainers/python:3.13-bookworm",
 	"features": {
 		"ghcr.io/devcontainers-contrib/features/pre-commit:2": {
 			"version": "latest"

.github/workflows/build-sphinx-docs.yml

@@ -22,14 +22,14 @@ defaults:
 jobs:
 
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.13'
           cache: pip
       - name: Run pre-commit
         run: |
@@ -39,7 +39,7 @@ jobs:
           pre-commit run -a -v --color always
       - name: Build docs
         run: |
-          nox -e 'docs-html(download_versions=True, clean=True)'
+          nox -e 'docs-html(gen_sitevars=True, clean=True)'
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
@@ -52,7 +52,7 @@ jobs:
   deploy:
     permissions:
       contents: write
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     needs:
       - build
     if: success() && startsWith(github.ref, 'refs/tags/')

.gitignore

@@ -74,8 +74,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 ## Generated stuff from Sphinx templates
-# docs/sitevars.rst
-# docs/topics/announcements.rst
+docs/sitevars.rst
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 ---
-minimum_pre_commit_version: 2.9.3
+minimum_pre_commit_version: 4.0.1
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0

.rstcheck.cfg

@@ -47,22 +47,24 @@ ignore_substitutions=
   windows-x86-exe-md5,
   windows-x86-exe-sha256,
   windows-amd64-exe-gpg,
-  macos-amd64-lts-download,
-  macos-arm64-lts-download,
-  macos-amd64-sts-download,
-  macos-arm64-sts-download,
-  minor-lts-version-badge,
-  minor-sts-version-badge,
-  windows-amd64-exe-lts-download,
-  windows-amd64-msi-lts-download,
-  windows-x86-exe-lts-download,
-  windows-x86-msi-lts-download,
-  windows-amd64-exe-sts-download,
-  windows-amd64-msi-sts-download,
-  windows-x86-exe-sts-download,
-  windows-x86-msi-sts-download,
-  minor-lts-version,
-  minor-sts-version,
-  relenv-lts-python-version,
-  relenv-sts-python-version,
+  macos-amd64-one-download,
+  macos-arm64-one-download,
+  macos-amd64-two-download,
+  macos-arm64-two-download,
+  minor-one-version-badge,
+  minor-two-version-badge,
+  windows-amd64-exe-one-download,
+  windows-amd64-msi-one-download,
+  windows-x86-exe-one-download,
+  windows-x86-msi-one-download,
+  windows-amd64-exe-two-download,
+  windows-amd64-msi-two-download,
+  windows-x86-exe-two-download,
+  windows-x86-msi-two-download,
+  minor-one-version,
+  minor-two-version,
+  relenv-one-python-version,
+  relenv-two-python-version,
+  major-one-version-text,
+  major-two-version-text
 ignore_messages=(.*(aix|arista)\.rst.* \(ERROR\/3\) Error in "code-block" directive\:$)

README.rst

@@ -10,10 +10,6 @@ Salt install guide
    :alt: PyPi Package Downloads
    :target: https://pypi.org/project/salt
 
-.. image:: https://img.shields.io/twitch/status/saltprojectoss
-   :alt: Salt Project Twitch Channel
-   :target: https://www.twitch.tv/saltprojectoss
-
 .. image:: https://img.shields.io/reddit/subreddit-subscribers/saltstack?style=social
    :alt: Salt Project subreddit
    :target: https://www.reddit.com/r/saltstack/
@@ -27,24 +23,21 @@ Salt install guide
 
 If you're looking to install Salt, you've come to the right place!
 
-- `View the Sphinx-built documentation here <https://saltstack.gitlab.io/open/docs/salt-install-guide>`__
-- `View the source repo here <https://gitlab.com/saltstack/open/docs/salt-install-guide>`__
+- `View the Sphinx-built documentation here <https://docs.saltproject.io/salt/install-guide/en/latest/>`__
+- `View the source repo here <https://github.com/saltstack/salt-install-guide>`__
 
 About the Salt install guide
 ============================
 
 The Salt Install Guide supplements and extends the core documentation for the
 `Salt Project <https://github.com/saltstack/salt>`__. This guide is intended to
-help Salt users install ``salt`` in their environment, ultimately superseding
-documentation where applicable:
-
-* Install directions on `docs.saltproject.io <https://docs.saltproject.io/en/master/topics/installation/index.html>`__
+help Salt users install ``salt`` in their environment.
 
 Contributions from anyone inside the Salt project community are always welcome.
 Please read the :ref:`contributing` for more information. The contributing
 guide can also be found in the source repository:
 
-* `CONTRIBUTING.rst <https://gitlab.com/saltstack/open/docs/salt-install-guide/-/blob/master/CONTRIBUTING.rst>`__
+* `CONTRIBUTING.rst <https://github.com/saltstack/salt-install-guide/-/blob/master/CONTRIBUTING.rst>`__
 
 
 Related links
@@ -77,7 +70,7 @@ The following documentation is part of the Salt Project documentation:
 * `Module documentation <https://docs.saltproject.io/en/latest/py-modindex.html>`__:
   The Salt modules and state modules explain the use cases and arguments needed
   to execute the Salt modules.
-* `Salt User Guide <https://saltstack.gitlab.io/open/docs/salt-user-guide/>`__:
+* `Salt User Guide <https://docs.saltproject.io/salt/user-guide/en/latest/>`__:
   The Salt User Guide supplements and extends the core documentation for the
   Salt Project. This guide is intended to help Salt users learn about Salt's
   core concepts and features. It was originally authored by Alan Cugler and
@@ -96,8 +89,28 @@ This repository uses the following tools:
   web.
 * Sphinx applies the
   `Furo Theme for Sphinx <https://pradyunsg.me/furo/>`__ to render the site.
-* The guide is hosted directly on GitLab using the
-  `GitLab pages <https://docs.gitlab.com/ee/user/project/pages/>`__ feature.
-* GitLab handles the
-  `CI/CD pipeline <https://gitlab.com/saltstack/open/docs/salt-install-guide/-/pipelines>`__
+* The guide is hosted directly on GitHub using the
+  `GitHub pages <https://pages.github.com/>`__ feature.
+* GitHub Actions handle the
+  `CI/CD pipelines <https://github.com/saltstack/salt-install-guide/actions>`__
   for the project.
+
+Release Process
+===============
+
+New releases of the ``salt-install-guide`` are required in order to ensure the latest docs changes
+make it into ``docs.saltproject.io``, which are collectively published via a private repository
+called ``builddocs``. ``builddocs`` will do the following:
+
+* Downloads the latest tarball builds from GitHub Releases of target docs repos
+    * ``salt-install-guide``
+    * ``salt-user-guide``
+* Build reference docs from ``salt`` repo for supported release versions
+
+To cut a new release of ``salt-install-guide``:
+
+* Create and push a new tag via git
+* The new tag will trigger a GitHub Action workflow which will create a new release
+    * The new release will include the latest built tarball!
+* Upon completion of a new ``salt-install-guide`` release, a new workflow must be launched
+  via ``builddocs`` if wanting these changes to be immediately live

docs/_templates/sitevars.rst

@@ -1,39 +1,45 @@
-.. |major-lts-version| replace:: 3006
-.. |major-sts-version| replace:: 3007
-.. |minor-lts-version| replace:: 3006.9
-.. |minor-sts-version| replace:: 3007.1
-.. |minor-lts-version-badge| replace:: :bdg-link-primary:`3006.9 <https://docs.saltproject.io/en/3006/topics/releases/3006.9.html>`
-.. |minor-sts-version-badge| replace:: :bdg-link-success:`3007.1 <https://docs.saltproject.io/en/latest/topics/releases/3007.1.html>`
-
-.. |relenv-lts-python-version| replace:: **Python v3.10.x**
-.. |relenv-sts-python-version| replace:: **Python v3.10.x**
+.. |major-latest-version| replace:: LATEST_MAJOR
+.. |major-one-version| replace:: ONE_MAJOR
+.. |major-two-version| replace:: TWO_MAJOR
+.. |major-latest-version-text| replace:: LATEST_MAJOR LATEST_SUPPORT_TYPE
+.. |major-one-version-text| replace:: ONE_MAJOR ONE_SUPPORT_TYPE
+.. |major-two-version-text| replace:: TWO_MAJOR TWO_SUPPORT_TYPE
+.. |major-two-version-repo-postfix| replace:: TWO_MAJOR-TWO_LOWER_SUPPORT_TYPE
+.. |minor-latest-version| replace:: LATEST_MINOR
+.. |minor-one-version| replace:: ONE_MINOR
+.. |minor-two-version| replace:: TWO_MINOR
+.. |minor-one-version-badge| replace:: :bdg-link-primary:`ONE_MINOR <https://docs.saltproject.io/en/ONE_MAJOR/topics/releases/ONE_MINOR.html>`
+.. |minor-two-version-badge| replace:: :bdg-link-success:`TWO_MINOR <https://docs.saltproject.io/en/TWO_MAJOR/topics/releases/TWO_MINOR.html>`
+
+.. |relenv-one-python-version| replace:: **Python vONE_RELENV_PYTHON.x**
+.. |relenv-two-python-version| replace:: **Python vTWO_RELENV_PYTHON.x**
 
 .. |quickstart-script-path| replace:: https://raw.githubusercontent.com/saltstack/salt-bootstrap/develop/salt-quick-start.sh
 .. |quickstart-script-path-windows| replace:: https://raw.githubusercontent.com/saltstack/salt-bootstrap/develop/salt-quick-start.ps1
 .. |windows-vs-buildtools-script| replace:: https://raw.githubusercontent.com/saltstack/salt/master/pkg/windows/install_vs_buildtools.ps1
 
-.. |release-candidate-version| replace:: RC_RELEASE
-.. |bootstrap-release-candidate| replace:: python3 git vRC_RELEASE
-.. |pip-install-release-candidate| replace:: pip install salt==RC_RELEASE
+.. |release-candidate-version| replace:: RC_FULL_VERSION
+.. |bootstrap-release-candidate| replace:: python3 git vRC_FULL_VERSION
+.. |pip-install-release-candidate| replace:: pip install salt==RC_FULL_VERSION
 
-.. |macos-amd64-lts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/3006.9/salt-3006.9-py3-x86_64.pkg
-.. |macos-arm64-lts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/3006.9/salt-3006.9-py3-arm64.pkg
+.. |macos-amd64-one-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/ONE_MINOR/salt-ONE_MINOR-py3-x86_64.pkg
+.. |macos-arm64-one-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/ONE_MINOR/salt-ONE_MINOR-py3-arm64.pkg
 
-.. |macos-amd64-sts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/3007.1/salt-3007.1-py3-x86_64.pkg
-.. |macos-arm64-sts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/3007.1/salt-3007.1-py3-arm64.pkg
+.. |macos-amd64-two-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/TWO_MINOR/salt-TWO_MINOR-py3-x86_64.pkg
+.. |macos-arm64-two-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/macos/TWO_MINOR/salt-TWO_MINOR-py3-arm64.pkg
 
-.. |windows-install-exe-example| replace:: Salt-Minion-3006.9-Py3-AMD64-Setup.exe
-.. |windows-install-msi-example| replace:: Salt-Minion-3006.9-Py3-AMD64.msi
+.. |windows-install-exe-example| replace:: Salt-Minion-ONE_MINOR-Py3-AMD64-Setup.exe
+.. |windows-install-msi-example| replace:: Salt-Minion-ONE_MINOR-Py3-AMD64.msi
 
-.. |windows-amd64-exe-lts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3006.9/Salt-Minion-3006.9-Py3-AMD64-Setup.exe
-.. |windows-amd64-msi-lts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3006.9/Salt-Minion-3006.9-Py3-AMD64.msi
-.. |windows-x86-exe-lts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3006.9/Salt-Minion-3006.9-Py3-x86-Setup.exe
-.. |windows-x86-msi-lts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3006.9/Salt-Minion-3006.9-Py3-x86.msi
+.. |windows-amd64-exe-one-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/ONE_MINOR/Salt-Minion-ONE_MINOR-Py3-AMD64-Setup.exe
+.. |windows-amd64-msi-one-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/ONE_MINOR/Salt-Minion-ONE_MINOR-Py3-AMD64.msi
+.. |windows-x86-exe-one-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/ONE_MINOR/Salt-Minion-ONE_MINOR-Py3-x86-Setup.exe
+.. |windows-x86-msi-one-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/ONE_MINOR/Salt-Minion-ONE_MINOR-Py3-x86.msi
 
-.. |windows-amd64-exe-sts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3007.1/Salt-Minion-3007.1-Py3-AMD64-Setup.exe
-.. |windows-amd64-msi-sts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3007.1/Salt-Minion-3007.1-Py3-AMD64.msi
-.. |windows-x86-exe-sts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3007.1/Salt-Minion-3007.1-Py3-x86-Setup.exe
-.. |windows-x86-msi-sts-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/3007.1/Salt-Minion-3007.1-Py3-x86.msi
+.. |windows-amd64-exe-two-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/TWO_MINOR/Salt-Minion-TWO_MINOR-Py3-AMD64-Setup.exe
+.. |windows-amd64-msi-two-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/TWO_MINOR/Salt-Minion-TWO_MINOR-Py3-AMD64.msi
+.. |windows-x86-exe-two-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/TWO_MINOR/Salt-Minion-TWO_MINOR-Py3-x86-Setup.exe
+.. |windows-x86-msi-two-download| replace:: https://packages.broadcom.com/artifactory/saltproject-generic/windows/TWO_MINOR/Salt-Minion-TWO_MINOR-Py3-x86.msi
 
 .. |windows-release-candidate-amd64-exe-file-name| replace:: TBD
 .. |windows-release-candidate-amd64-exe-url| replace:: TBD

docs/conf.py

@@ -16,7 +16,7 @@
 import datetime
 import os
 
-import requests
+# import requests
 from docutils import nodes
 from docutils.nodes import Element
 from sphinx.writers.html import HTMLTranslator
@@ -93,39 +93,12 @@ def setup(app):
 )
 
 # Pull release from "release" in sitevars.rst
-release = [s for s in site_vars if "|minor-lts-version|" in s][0].split(":: ")[1]
+release = [s for s in site_vars if "|minor-one-version|" in s][0].split(":: ")[1]
 version = release
 
 # Grab major version for URL version selector generation
 current_version = version.split(".")[0]
 
-##
-# Furo theme version selector setup
-##
-# Pull from JSON in GitLab Snippet
-"""
-supported_versions_json = requests.get(
-    "https://gitlab.com/saltstack/open/docs/salt-install-guide/-/snippets/2580440/raw/main/supported-versions.json"
-)
-supported_versions = supported_versions_json.json()
-supported_major_versions = [
-    full_version.split(".")[0]
-    for full_version in supported_versions["supported_versions"]
-]
-supported_major_versions.sort()
-
-# Build out version menu
-latest_version = supported_versions["latest_version"].split(".")[0]
-versions = supported_major_versions
-url_prefix = "https://docs.saltproject.io/salt/install-guide/en/"
-html_context = make_html_context(
-    url_prefix=url_prefix,
-    current_version=current_version,
-    latest_version=latest_version,
-    versions=versions,
-)
-"""
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -182,7 +155,7 @@ def setup(app):
         "color-brand-primary": "#66CCF4",
         "color-brand-content": "#66CCF4",
     },
-    "announcement": '<font color="orange"><strong>IMPORTANT ANNOUNCEMENT:</strong> repo.saltproject.io has migrated to packages.broadcom.com!<br /><strong><a href="https://saltproject.io/blog/post-migration-salt-project-faqs/" target="_blank" rel="noopener noreferrer">Click here for latest update (2024-11-22)</a></strong></font>',
+    "announcement": '<font color="orange"><strong>IMPORTANT ANNOUNCEMENT:</strong> repo.saltproject.io has migrated to packages.broadcom.com!<br /><strong><a href="https://saltproject.io/blog/post-migration-salt-project-faqs/" target="_blank" rel="noopener noreferrer">Click here for migration FAQs (2024-11-22)</a></strong></font>',
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/requirements.txt

@@ -1,5 +1,4 @@
 furo>=2024.8.6
-requests>=2.31.0
 sphinx-copybutton>=0.5.2
 sphinx-design>=0.5.0
 sphinx-inline-tabs>=2023.4.21