Skip to content

Commit

Permalink
Merge pull request #21 from ScriptAutomate/sitevars-autoupdate
Browse files Browse the repository at this point in the history
Use sitevars, nox, and json to update versions
  • Loading branch information
ScriptAutomate authored Jan 10, 2025
2 parents 51ff19d + 33f4630 commit 3429e4b
Show file tree
Hide file tree
Showing 30 changed files with 289 additions and 408 deletions.
2 changes: 1 addition & 1 deletion .devcontainer.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/build-sphinx-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand All @@ -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:
Expand All @@ -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/')
Expand Down
3 changes: 1 addition & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
38 changes: 20 additions & 18 deletions .rstcheck.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -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\:$)
45 changes: 29 additions & 16 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
58 changes: 32 additions & 26 deletions docs/_templates/sitevars.rst
Original file line number Diff line number Diff line change
@@ -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
Expand Down
33 changes: 3 additions & 30 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
1 change: 0 additions & 1 deletion docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -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
Expand Down
42 changes: 0 additions & 42 deletions docs/sitevars.rst

This file was deleted.

Loading

0 comments on commit 3429e4b

Please sign in to comment.