diff --git a/common.mk b/common.mk index 1e8f8854..3ce5db34 100644 --- a/common.mk +++ b/common.mk @@ -3,11 +3,12 @@ SOURCES=$(wildcard *.py) $(PROJECT) tests -# Env vars for the docs Starter Pack. They must be exported so make can pass them to the +# Env vars for the docs Sphinx Stack. They must be exported so make can pass them to the # docs Makefile. export DOCS_BUILDDIR ?= _build export DOCS_VENVDIR ?= ../.venv export VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale +export SPHINX_AUTOBUILD_OPTS ?= --ignore "$(DOCS_VENVDIR)/*" --ignore "reference/commands/*" -D=llms_txt_enabled=0 ifneq ($(OS),Windows_NT) OS := $(shell uname) diff --git a/docs/.gitignore b/docs/.gitignore index aad78f1f..3006f13e 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,17 +1,17 @@ # Environment *env*/ -.sphinx/venv/ +.venv/ # Sphinx -.sphinx/warnings.txt -.sphinx/.wordlist.dic -.sphinx/.doctrees/ -.sphinx/update/ -.sphinx/node_modules/ +_dev/warnings.txt +_dev/.wordlist.dic +_dev/.doctrees/ +_dev/update/ +_dev/node_modules/ # Vale -.sphinx/styles/* -.sphinx/vale.ini +_dev/styles/* +_dev/vale.ini # Build outputs _build diff --git a/docs/.sphinx/version b/docs/.sphinx/version deleted file mode 100644 index c239c60c..00000000 --- a/docs/.sphinx/version +++ /dev/null @@ -1 +0,0 @@ -1.5 diff --git a/docs/Makefile b/docs/Makefile index f9d27127..ce545cdb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,22 +5,23 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINX_DIR ?= .sphinx -SPHINX_OPTS ?= -c . -d $(SPHINX_DIR)/.doctrees -j auto -SPHINX_BUILD ?= $(DOCS_VENVDIR)/bin/sphinx-build -SPHINX_HOST ?= 127.0.0.1 -SPHINX_PORT ?= 8000 -DOCS_VENVDIR ?= $(SPHINX_DIR)/venv -DOCS_VENV ?= $(DOCS_VENVDIR)/bin/activate -DOCS_SOURCEDIR ?= . -DOCS_BUILDDIR ?= _build -DOCS_PDFPACKAGES ?= latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng -DOCS_VOCAB ?= $(SPHINX_DIR)/styles/config/vocabularies/Canonical -VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale -VALE_CONFIG ?= $(SPHINX_DIR)/vale.ini -PA11Y_CMD ?= $(SPHINX_DIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINX_DIR)/pa11y.json -CONFIRM_SUDO ?= N -CHECK_PATH ?= * +DEV_DIR ?= _dev +SPHINX_OPTS ?= -c . -d $(DEV_DIR)/.doctrees -j auto +SPHINX_BUILD ?= $(DOCS_VENVDIR)/bin/sphinx-build +SPHINX_HOST ?= 127.0.0.1 +SPHINX_PORT ?= 8000 +SPHINX_AUTOBUILD_OPTS ?= -D=llms_txt_enabled=0 +DOCS_VENVDIR ?= .venv +DOCS_VENV ?= $(DOCS_VENVDIR)/bin/activate +DOCS_SOURCEDIR ?= . +DOCS_BUILDDIR ?= _build +DOCS_PDFPACKAGES ?= latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng +DOCS_VOCAB ?= $(DEV_DIR)/styles/config/vocabularies/Canonical +VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale +VALE_CONFIG ?= $(DEV_DIR)/vale.ini +PA11Y_CMD ?= $(DEV_DIR)/node_modules/pa11y/bin/pa11y.js --config $(DEV_DIR)/pa11y.json +CONFIRM_SUDO ?= N +CHECK_PATH ?= $(filter-out $(DOCS_VENVDIR) $(DOCS_BUILDDIR),$(wildcard *)) # Put it first so that "make" without argument is like "make help". help: @@ -68,8 +69,8 @@ $(DOCS_VENVDIR): pa11y-install: @command -v $(PA11Y_CMD) >/dev/null || { \ echo "Installing \"pa11y\" from npm..."; echo; \ - mkdir -p $(SPHINX_DIR)/node_modules/ ; \ - npm install --prefix $(SPHINX_DIR) pa11y; \ + mkdir -p $(DEV_DIR)/node_modules/ ; \ + npm install --prefix $(DEV_DIR) pa11y; \ } pymarkdownlnt-install: install @@ -78,14 +79,14 @@ pymarkdownlnt-install: install install: $(DOCS_VENVDIR) run: install - . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) + . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(SPHINX_AUTOBUILD_OPTS) # Does not depend on $(DOCS_BUILDDIR) to rebuild properly at every run. html: install - . $(DOCS_VENV); $(SPHINX_BUILD) --fail-on-warning --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) + . $(DOCS_VENV); $(SPHINX_BUILD) --fail-on-warning --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(DEV_DIR)/warnings.txt $(SPHINX_OPTS) epub: install - . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS) + . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(DEV_DIR)/warnings.txt $(SPHINX_OPTS) serve: html cd "$(DOCS_BUILDDIR)"; python3 -m http.server --bind $(SPHINX_HOST) $(SPHINX_PORT) @@ -93,13 +94,13 @@ serve: html clean: clean-doc @test ! -e "$(DOCS_VENVDIR)" -o -d "$(DOCS_VENVDIR)" -a "$(abspath $(DOCS_VENVDIR))" != "$(DOCS_VENVDIR)" rm -rf $(DOCS_VENVDIR) - rm -rf $(SPHINX_DIR)/node_modules/ - rm -rf $(SPHINX_DIR)/styles + rm -rf $(DEV_DIR)/node_modules/ + rm -rf $(DEV_DIR)/styles rm -rf $(VALE_CONFIG) clean-doc: git clean -fx "$(DOCS_BUILDDIR)" - rm -rf $(SPHINX_DIR)/.doctrees + rm -rf $(DEV_DIR)/.doctrees linkcheck: install . $(DOCS_VENV) ; $(SPHINX_BUILD) -b linkcheck -q "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) || { grep --color -F "[broken]" "$(DOCS_BUILDDIR)/output.txt"; exit 1; } @@ -108,35 +109,52 @@ linkcheck: install pa11y: pa11y-install html find $(DOCS_BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y_CMD) +# Without --return-code-scheme explicit, pymarkdownlnt returns 1 for multiple scenarios +# By using the explicit scheme, it only returns 1 when no files are found, +# which should not result in failure lint-md: pymarkdownlnt-install - @. $(DOCS_VENV); pymarkdownlnt --config $(SPHINX_DIR)/.pymarkdown.json scan --recurse --exclude=$(SPHINX_DIR)/** $(DOCS_SOURCEDIR) + @. $(DOCS_VENV); pymarkdownlnt \ + --config $(DEV_DIR)/.pymarkdown.json \ + --return-code-scheme explicit \ + scan \ + --recurse \ + --exclude=$(DEV_DIR)/** \ + --exclude=$(DOCS_VENVDIR)/** \ + $(DOCS_SOURCEDIR); \ + status=$$?; \ + if [ $$status -eq 1 ]; then \ + echo "No Markdown files selected for linting"; \ + exit 0; \ + fi; \ + echo "pymarkdownlnt exited with code $$status"; \ + exit $$status; vale-install: install - @. $(DOCS_VENV); test -f $(VALE_CONFIG) || python3 $(SPHINX_DIR)/get_vale_conf.py - @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINX_DIR)/styles/woke.filter - @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/error.filter - @echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/spelling.filter + @. $(DOCS_VENV); test -f $(VALE_CONFIG) || python3 $(DEV_DIR)/get_vale_conf.py + @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(DEV_DIR)/styles/woke.filter + @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(DEV_DIR)/styles/error.filter + @echo '.Name=="Canonical.000-US-spellcheck"' > $(DEV_DIR)/styles/spelling.filter @. $(DOCS_VENV); find $(VALE_DIR)/vale_bin -size 195c -exec vale --version \; woke: vale-install @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt @echo "Running Vale acceptable term check against $(CHECK_PATH). To change target set CHECK_PATH= with make command" - @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/woke.filter' --glob='*.{md,rst}' $(CHECK_PATH) + @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(DEV_DIR)/styles/woke.filter' --glob='*.{md,rst}' $(CHECK_PATH) @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt vale: vale-install @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command" - @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/error.filter' --glob='*.{md,rst}' $(CHECK_PATH) + @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(DEV_DIR)/styles/error.filter' --glob='*.{md,rst}' $(CHECK_PATH) @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt spelling: vale-install @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command" - @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/spelling.filter' --glob='*.{md,rst}' $(CHECK_PATH) + @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(DEV_DIR)/styles/spelling.filter' --glob='*.{md,rst}' $(CHECK_PATH) @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt spellcheck: spelling @@ -165,7 +183,7 @@ pdf: pdf-prep @echo update: install - @. $(DOCS_VENV); .sphinx/update_sp.py + @. $(DOCS_VENV); _dev/update_sp.py # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINX_OPTS). diff --git a/docs/README.md b/docs/README.md index 46bd0cbe..f7cd7acb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,17 @@ # Documentation subproject -The documentation build configuration is stored as its own subproject, a copy of -[Canonical's Sphinx Starter -Pack](https://github.com/canonical/sphinx-docs-starter-pack). Updating and managing this -subproject happens separately from the main app. +The documentation build configuration is stored as its own subproject, a copy of the +[Sphinx Stack](https://github.com/canonical/sphinx-stack). Updating and +managing this subproject happens separately from the main app. -The [Starter Pack documentation](https://canonical-starter-pack.readthedocs-hosted.com) +The [Sphinx Stack documentation](https://documentation.ubuntu.com/sphinx-stack) describes the officially-supported features and provides guidance for customizing the docs. ## Update the docs subproject -The goal is to override the build configuration of the starter pack as little as -possible, so when changes come we don't have to create them. The process isn't completely automatic. +The goal is to override the build configuration of the Sphinx Stack as little as +possible, so when changes come we don't have to create them. The process isn't +completely automatic. First, run the update script: @@ -22,14 +22,14 @@ make docs-update The script will inform you of the files that have changed. Go through each notification and make the proper adjustments so the new and updated features work properly. -In `pyproject.toml`, remove everything in the `docs-starter-pack` group. +In `pyproject.toml`, remove everything in the `docs-sphinx-stack` group. Then, sync the docs dependencies to the parent project: ```bash make clean make docs-setup -uv add -r docs/requirements.txt --group docs-starter-pack +uv add -r docs/requirements.txt --group docs-sphinx-stack ``` In `docs/Makefile`, make sure these lines are changed like so: diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/_dev/.pre-commit-config.yaml similarity index 100% rename from docs/.sphinx/.pre-commit-config.yaml rename to docs/_dev/.pre-commit-config.yaml diff --git a/docs/.sphinx/.pymarkdown.json b/docs/_dev/.pymarkdown.json similarity index 100% rename from docs/.sphinx/.pymarkdown.json rename to docs/_dev/.pymarkdown.json diff --git a/docs/.sphinx/get_vale_conf.py b/docs/_dev/get_vale_conf.py similarity index 97% rename from docs/.sphinx/get_vale_conf.py rename to docs/_dev/get_vale_conf.py index 13e7966f..b09404ae 100755 --- a/docs/.sphinx/get_vale_conf.py +++ b/docs/_dev/get_vale_conf.py @@ -15,7 +15,7 @@ datefmt='%Y-%m-%d %H:%M:%S' ) -SPHINX_DIR = os.path.join(os.getcwd(), ".sphinx") +DEV_DIR = os.path.join(os.getcwd(), "_dev") GITHUB_REPO = "canonical/documentation-style-guide" GITHUB_CLONE_URL = f"https://github.com/{GITHUB_REPO}.git" @@ -133,7 +133,7 @@ def parse_arguments(): def main(): # Define local directory paths - vale_files_dict = {file: os.path.join(SPHINX_DIR, file) for file in VALE_FILE_LIST} + vale_files_dict = {file: os.path.join(DEV_DIR, file) for file in VALE_FILE_LIST} # Parse command line arguments, default to overwrite_enabled = True overwrite_enabled = not parse_arguments().no_overwrite diff --git a/docs/.sphinx/pa11y.json b/docs/_dev/pa11y.json similarity index 100% rename from docs/.sphinx/pa11y.json rename to docs/_dev/pa11y.json diff --git a/docs/.sphinx/update_sp.py b/docs/_dev/update_sp.py similarity index 85% rename from docs/.sphinx/update_sp.py rename to docs/_dev/update_sp.py index a9259d02..4923a33e 100755 --- a/docs/.sphinx/update_sp.py +++ b/docs/_dev/update_sp.py @@ -1,11 +1,11 @@ #! /usr/bin/env python -# Initial update script for the starter pack. +# Initial update script for the Sphinx Stack. # # Requires some manual intervention, but makes identifying updates and differences easier. # # For debugging, please run this script with DEBUGGING=1 -# e.g. user@device:~/git/Canonical/sphinx-docs-starter-pack/docs$ DEBUGGING=1 python .sphinx/update_sp.py +# e.g. user@device:~/git/Canonical/sphinx-stack/docs$ DEBUGGING=1 python _dev/update_sp.py import glob @@ -19,12 +19,12 @@ from packaging.version import parse as parse_version SPHINX_DIR = os.path.abspath(os.path.dirname(__file__)) -DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, '..')) +DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, "..")) REQUIREMENTS = os.path.join(DOCS_DIR, "requirements.txt") SPHINX_UPDATE_DIR = os.path.join(SPHINX_DIR, "update") -GITHUB_REPO = "canonical/sphinx-docs-starter-pack" +GITHUB_REPO = "canonical/sphinx-stack" GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}" -GITHUB_API_SPHINX_DIR = f"{GITHUB_API_BASE}/contents/docs/.sphinx" +GITHUB_API_DEV_DIR = f"{GITHUB_API_BASE}/contents/docs/_dev" GITHUB_RAW_BASE = f"https://raw.githubusercontent.com/{GITHUB_REPO}/main" TIMEOUT = 10 # seconds @@ -43,7 +43,7 @@ def main(): except FileNotFoundError: print("WARNING\nWARNING\nWARNING") print( - "You need to update to at least version 1.0.0 of the starter pack to start using the update function." + "You need to update to at least version 1.0.0 of the Sphinx Stack to start using the update function." ) print("You may experience issues using this functionality.") logging.debug("No local version found. Setting version to None") @@ -61,15 +61,15 @@ def main(): logging.debug("Comparing versions") if parse_version(local_version) < parse_version(latest_release): logging.debug("Local version is older than the release version.") - print("Starter pack is out of date.\n") + print("Sphinx Stack is out of date.\n") - # Identify and download '.sphinx' dir files to '.sphinx/update' + # Identify and download '_dev' dir files to '_dev/update' files_updated, new_files = update_static_files() - # Write new version to file to '.sphinx/update' + # Write new version to file to '_dev/update' download_file( - GITHUB_RAW_BASE + "/docs/.sphinx/version", + GITHUB_RAW_BASE + "/docs/_dev/version", os.path.join(SPHINX_UPDATE_DIR, "version"), ) @@ -84,8 +84,8 @@ def main(): if files_updated: logging.debug("Updated files found and downloaded") print("Differences have been identified in static files.") - print("Updated files have been downloaded to '.sphinx/update'.") - print("Validate and move these files into your '.sphinx/' directory.") + print("Updated files have been downloaded to '_dev/update'.") + print("Validate and move these files into your '_dev/' directory.") else: logging.debug("No files found to update") # Provide information on NEW files @@ -94,7 +94,7 @@ def main(): print( "NOTE: New files have been downloaded\n", "See 'NEWFILES.txt' for all downloaded files\n", - "Validate and merge these files into your '.sphinx/' directory", + "Validate and merge these files into your '_dev/' directory", ) else: logging.debug("No new files found to download") @@ -130,19 +130,19 @@ def main(): except FileNotFoundError: print("requirements.txt not found") print( - "The updated starter pack has moved requirements.txt out of the '.sphinx' dir" + "The updated Sphinx Stack has moved requirements.txt out of the '_dev' dir" ) print("requirements.txt not checked, please update your requirements manually") def update_static_files(): - """Checks local files against remote for new and different files, downloads to '.sphinx/updates'""" + """Checks local files against remote for new and different files, downloads to '_dev/updates'""" files, paths = get_local_files_and_paths() new_file_list = [] - for item in query_api(GITHUB_API_SPHINX_DIR).json(): + for item in query_api(GITHUB_API_DEV_DIR).json(): logging.debug(f"Checking {item['name']}") - # Checks existing files in '.sphinx' starter pack static root for changed SHA + # Checks existing files in '_dev' Sphinx Stack static root for changed SHA if item["name"] in files and item["type"] == "file": index = files.index(item["name"]) if item["sha"] != get_git_revision_hash(paths[index]): @@ -154,17 +154,15 @@ def update_static_files(): # Indicate update script needs to be updated and re-run print("WARNING") print( - "THIS UPDATE SCRIPT IS OUT OF DATE. YOU MAY NEED TO RUN ANOTHER UPDATE AFTER UPDATING TO THE FILE IN '.sphinx/updates'." + "THIS UPDATE SCRIPT IS OUT OF DATE. YOU MAY NEED TO RUN ANOTHER UPDATE AFTER UPDATING TO THE FILE IN '_dev/updates'." ) print("WARNING\n") else: logging.debug("File hashes are equal") - # Checks nested files '.sphinx/**/**.*' for changed SHA (single level of depth) + # Checks nested files '_dev/**/**.*' for changed SHA (single level of depth) elif item["type"] == "dir": logging.debug(item["name"] + " is a directory") - for nested_item in query_api( - f"{GITHUB_API_SPHINX_DIR}/{item['name']}" - ).json(): + for nested_item in query_api(f"{GITHUB_API_DEV_DIR}/{item['name']}").json(): logging.debug(f"Checking {nested_item['name']}") if nested_item["name"] in files: index = files.index(nested_item["name"]) @@ -189,7 +187,7 @@ def update_static_files(): SPHINX_UPDATE_DIR, item["name"], nested_item["name"] ), ) - # Downloads NEW files in '.sphinx' starter pack static root + # Downloads NEW files in '_dev' Sphinx Stack static root else: if item["type"] == "file": logging.debug(f"No local version found of {item['name']}") @@ -225,7 +223,7 @@ def get_git_revision_hash(file) -> str: # Examines local files def get_local_files_and_paths(): - """Identify '.sphinx' local files and paths""" + """Identify '_dev' local files and paths""" logging.debug("Checking local files and paths") try: files = [] diff --git a/docs/_dev/version b/docs/_dev/version new file mode 100644 index 00000000..cd5ac039 --- /dev/null +++ b/docs/_dev/version @@ -0,0 +1 @@ +2.0 diff --git a/docs/_static/css/cookie-banner.css b/docs/_static/css/cookie-banner.css deleted file mode 100644 index e487b96d..00000000 --- a/docs/_static/css/cookie-banner.css +++ /dev/null @@ -1,82 +0,0 @@ -/* Cookie policy styling WILL BE REMOVED when implementation of new theme with vanilla is implemented */ -.cookie-policy { - overflow: auto; - top: 35%; - z-index: 50; - position: fixed; -} - -dialog.cookie-policy { - background-color: var(--color-code-background); - color: var(--color-code-foreground); - height: auto; - max-height: 60vh; - max-width: 40rem; - padding: 0 1rem 0 1rem; - width: auto; -} - -header.p-modal__header { - margin-bottom: 0.5rem; -} - -header.p-modal__header::after { - background-color: #d9d9d9; - content: ""; - height: 1px; - left: 0; - margin-left: 1rem; - margin-right: 1rem; - position: absolute; - right: 0; -} - -h2#cookie-policy-title.p-modal__title { - align-self: flex-end; - font-size: 1.5rem; - font-style: normal; - font-weight: 275; - line-height: 2rem; - margin: 0 0 1.05rem 0; - padding: 0.45rem 0 0 0; -} - -.cookie-policy p { - font-size: 1rem; - line-height: 1.5rem; - margin-top: 0; - padding-top: 0.4rem; -} - -.cookie-policy p a { - text-decoration: none; - color: var(--color-link); -} -.cookie-policy button { - border-style: solid; - border-width: 1.5px; - cursor: pointer; - display: inline-block; - font-size: 1rem; - font-weight: 400; - justify-content: center; - line-height: 1.5rem; - padding: calc(0.4rem - 1px) 1rem; - text-align: center; - text-decoration: none; - transition-duration: 0.1s; - transition-property: background-color, border-color; - transition-timing-function: cubic-bezier(0.55, 0.055, 0.675, 0.19); -} - -.cookie-policy button { - background-color: #fff; - border-color: rgba(0, 0, 0, 0.56); - color: #000; -} - -.cookie-policy .p-button--positive { - background-color: #0e8420; - border-color: #0e8420; - color: #fff; -} diff --git a/docs/_static/js/bundle.js b/docs/_static/js/bundle.js deleted file mode 100644 index a79e20ca..00000000 --- a/docs/_static/js/bundle.js +++ /dev/null @@ -1 +0,0 @@ -(()=>{"use strict";function e(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function t(t){for(var n=1;ncookie policy.',buttonAccept:"Accept all and visit site",buttonManage:"Manage your tracker settings"},manager:{title:"Tracking choices",body1:"We use cookies to recognise visitors and remember your preferences.",body2:"They enhance user experience, personalise content and ads, provide social media features, measure campaign effectiveness, and analyse site traffic.",body3:"Select the types of trackers you consent to, both by us, and third parties.",body4:'Learn more at data privacy: cookie policy - you can change your choices at any time from the footer of the site.',acceptAll:"Accept all",acceptAllHelp:'This will switch all toggles "ON".',SavePreferences:"Save preferences"}},zh:{notification:{title:"您的追踪器设置",body1:"我们使用cookie和相似的方法来识别访问者和记住偏好设置。我们也用它们来衡量活动的效果和网站流量分析。",body2:"选择”接受“，您同意我们和受信的第三方来使用这些方式。",body3:'更多内容或者随时地变更您的同意选择，请点击我们的 cookie策略.',buttonAccept:"接受全部和访问网站",buttonManage:"管理您的追踪器设置"},manager:{title:"追踪选项",body1:"我们使用cookie来识别访问者和记住您的偏好设置",body2:"它们增强用户体验，使内容和广告个性化，提供社交媒体功能，衡量活动效果和网站流量分析。",body3:"选择您同意授予我们和受信的第三方的追踪类型。",body4:'点击数据隐私：cookie策略了解更多，您可以在网站底部随时更改您的选择。',acceptAll:"接受全部",acceptAllHelp:"这将把全部开关变为”开启“。",SavePreferences:"保存偏好设置"}},ja:{notification:{title:"トラッキング機能の設定",body1:"当社は、当社のウェブサイトを訪問された方の識別や傾向の記録を行うために、クッキーおよび類似の手法を利用します。また、キャンペーンの効果の測定やサイトのトラフィックの分析にもクッキーを利用します。",body2:"「同意」を選択すると、当社および信頼できる第三者による上記の手法の利用に同意したものとみなされます。",body3:'詳細または同意の変更については、いつでも当社のクッキーに関するポリシーをご覧になることができます。',buttonAccept:"すべて同意してサイトにアクセス",buttonManage:"トラッキング機能の設定の管理"},manager:{title:"トラッキング機能の選択",body1:"当社は、当社のウェブサイトを訪問された方の識別や傾向の記録を行うために、クッキーを利用します。",body2:"クッキーは、お客様の利便性の向上、お客様に合わせたコンテンツや広告の表示、ソーシャルメディア機能の提供、キャンペーンの効果の測定、サイトのトラフィックの分析に役立ちます。",body3:"当社および第三者によるトラッキング機能のタイプから、お客様が同意されるものをお選びください。",body4:'詳細は、データプライバシー：クッキーに関するポリシーをご覧ください。お客様が選んだ設定は、本サイトの下部からいつでも変更できます。',acceptAll:"すべて同意",acceptAllHelp:"同意されるとすべての設定が「ON」に切り替わります。",SavePreferences:"設定を保存"}}},d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"denied"},u=["security_storage"],p=["ad_storage","ad_user_data","ad_personalization","analytics_storage"],f=["functionality_storage","personalization_storage"],h=["ad_storage","ad_user_data","ad_personalization","analytics_storage","functionality_storage","personalization_storage"],y=function(e){var t=new Date;t.setTime(t.getTime()+31536e6);var n="expires="+t.toUTCString();document.cookie="_cookies_accepted="+e+"; "+n+"; samesite=lax;path=/;",S(e)&&_()},b=function(){for(var e=document.cookie.split(";"),t="",n="",o=0;o\n ")}},{key:"render",value:function(e){this.container.innerHTML=this.getNotificationMarkup(e),this.initaliseListeners()}},{key:"initaliseListeners",value:function(){var e=this;this.container.querySelector(".js-close").addEventListener("click",(function(t){y("all"),v("all"),e.destroyComponent()})),this.container.querySelector(".js-manage").addEventListener("click",(function(t){e.renderManager()}))}}]),e}(),L=function(){function e(t,n,i){o(this,e),this.language=i,this.id=t.id,this.title=m(t,i).title,this.description=m(t,i).description,this.enableSwitcher=t.enableSwitcher,this.container=n,this.element,this.render()}return a(e,[{key:"render",value:function(){var e=this.cookieIsTrue(),t=document.createElement("div");t.classList.add("u-sv3"),t.innerHTML="\n ".concat(''),"\n

",this.title,"

\n

").concat(this.description,"

"),this.container.appendChild(t),this.element=t.querySelector(".js-".concat(this.id,"-switch"))}},{key:"cookieIsTrue",value:function(){var e=b();return!(!e||e!==this.id&&"all"!==e)||e&&e===this.id}},{key:"isChecked",value:function(){return!!this.element&&this.element.checked}},{key:"getId",value:function(){return this.id}}]),e}(),E=function(){function e(t,n){o(this,e),this.container=t,this.controlsStore=[],this.destroyComponent=n}return a(e,[{key:"getManagerMarkup",value:function(e){var t=g(e).manager;return'\n ")}},{key:"render",value:function(e){var t=this;this.container.innerHTML=this.getManagerMarkup(e);var n=this.container.querySelector(".controls");s.forEach((function(o){var i=new L(o,n,e);t.controlsStore.push(i)})),this.initaliseListeners()}},{key:"initaliseListeners",value:function(){var e=this;this.container.querySelector(".js-close").addEventListener("click",(function(){y("all"),v("all"),e.destroyComponent()})),this.container.querySelector(".js-save-preferences").addEventListener("click",(function(){e.savePreferences(),e.destroyComponent()}))}},{key:"savePreferences",value:function(){var e=this.controlsStore.filter((function(e){return e.isChecked()}));this.controlsStore.length===e.length?y("all"):this.controlsStore.forEach((function(e){e.isChecked()&&y(e.getId())})),function(e){var n=e.filter((function(e){return e.isChecked()})),o=t({},d);n.forEach((function(e){o=k(o,e.id)})),w(o)}(this.controlsStore)}}]),e}();window.gtag||(window.dataLayer=window.dataLayer||[],window.gtag=function(){dataLayer.push(arguments)},window.gtag("consent","default",d));var O=function(){var e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:null,t=null,n=document.documentElement.lang,o=!1,i=function(e){e&&e.preventDefault(),null===t&&((t=document.createElement("dialog")).classList.add("cookie-policy"),t.setAttribute("open",!0),document.body.appendChild(t),new j(t,a,r).render(n),document.getElementById("cookie-policy-button-accept").focus())},a=function(){new E(t,r).render(n)},r=function(){"function"==typeof e&&e(),document.body.removeChild(t),t=null},c=function(){if(!o){var e;o=!0,(e=b())&&v(e);var t=document.querySelector(".js-revoke-cookie-manager");t&&t.addEventListener("click",i),function(){var e=b();return!e||"true"==e}()&&"hide"!==new URLSearchParams(window.location.search).get("cp")&&i()}};"loading"===document.readyState?document.addEventListener("DOMContentLoaded",c,!1):c()},P=function(e){document.cookie.match(new RegExp("(^| )"+e+"=([^;]+)"))},A=P("_cookies_accepted");function M(){var e,t;if(("all"===(null===(e=A=P("_cookies_accepted"))||void 0===e?void 0:e[2])||"performance"===(null===(t=A)||void 0===t?void 0:t[2]))&&!P("user_id")){var n=([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,(function(e){return(e^crypto.getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)}));document.cookie="user_id="+n+";max-age=31536000;",dataLayer.push({user_id:n})}}A?(M(),O()):O(M)})(); diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html new file mode 100644 index 00000000..436cfec8 --- /dev/null +++ b/docs/_templates/footer.html @@ -0,0 +1,103 @@ +
+ {# mod: Per-page navigation #} + {% if meta %} + {% if 'sequential_nav' in meta %} + {% set sequential_nav = meta.sequential_nav %} + {% endif %} + {% endif %} + {# mod: Conditional wrappers to control page navigation buttons #} + {% if sequential_nav != "none" -%} + {% if next and (sequential_nav == "next" or sequential_nav == "both") -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(root_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e -%} + © {{ copyright }} {{ author }} + {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} + © {{ copyright }} {{ author }} + {%- endtrans %} + {%- endif %} +
+ {%- endif %} + {%- if license and license.name -%} + {%- if license.url -%} +
+ This page is licensed under {{ license.name }} +
+ {%- else -%} +
+ This page is licensed under {{ license.name }} +
+ {%- endif -%} + {%- endif -%} + + {# mod: removed "Made with" #} + + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} + + {%- if show_source and has_source and sourcename %} +
+ Show source +
+ {%- endif %} +
+
+ {% if has_contributor_listing and display_contributors and pagename and page_source_suffix %} + {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %} + {% if contributors %} + {% if contributors | length > 1 %} + Thanks to the {{ contributors |length }} contributors! + {% else %} + Thanks to our contributor! + {% endif %} +
+ + {% endif %} + {% endif %} +
+
Manage your tracker settings
+
diff --git a/docs/_templates/header.html b/docs/_templates/header.html new file mode 100644 index 00000000..1c4e18b2 --- /dev/null +++ b/docs/_templates/header.html @@ -0,0 +1,72 @@ + diff --git a/docs/conf.py b/docs/conf.py index ab37e09d..c911c2a2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,14 +1,18 @@ import datetime import os +import textwrap # Configuration for the Sphinx documentation builder. # All configuration specific to your project should be done in this file. # +# If you're new to Sphinx and don't want any advanced or custom features, +# just go through the items marked 'TODO'. +# # A complete list of built-in Sphinx configuration values: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -# Our starter pack uses the custom Canonical Sphinx extension -# to keep all documentation based on it consistent and on brand: +# The Sphinx Stack uses the Canonical Sphinx theme to keep all documentation consistent +# and on brand: # https://github.com/canonical/canonical-sphinx @@ -17,11 +21,14 @@ ####################### # Project name +# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server") project = "Starbase" + +# Author name; used in the default copyright statement in the page footer author = "Canonical Ltd." -# Format the product name + version for the TOC and HTML title -# When the product begins versioning, uncomment this block +# Format the product name and version for the TOC and HTML title +# TODO: When the product begins versioning, uncomment this block. # release = .__version__ # if ".post" in release: # release = "dev" @@ -29,36 +36,51 @@ # major, minor, *_ = release.split(".") # release = f"{major}.{minor}" -# Copyright string; shown at the bottom of the page -copyright = f"2023-{datetime.date.today().year}, {author}" +# The year in the copyright statement +copyright = f"2023-{datetime.date.today().year}" + +# Sidebar documentation title +# To disable the title, set it to an empty string. +html_title = project + " documentation" # Documentation website URL ogp_site_url = "https://canonical-starbase.readthedocs-hosted.com/" # Preview name of the documentation website +# TODO: To use a different name for the project in previews, update the next line. ogp_site_name = project # Preview image URL -# -# TODO: To customise the preview image, update as needed. +# TODO: To customise the preview image, update the next line. ogp_image = "https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg" # Product favicon; shown in bookmarks, browser tabs, etc. +# TODO: To customise the favicon, uncomment and update the next line. # html_favicon = ".sphinx/_static/favicon.png" # Dictionary of values to pass into the Sphinx context for all pages: # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context html_context = { # Product page URL; can be different from product docs URL + # TODO: Change to your product website URL, dropping the 'https://' prefix (e.g., + # 'ubuntu.com/lxd'). If there's no such website, remove the {{ product_page }} + # link from the _templates/header.html file. "product_page": "github.com/canonical/starbase", # Product tag image; the orange part of your logo, shown in the page header # "product_tag": "_static/tag.png", + # Your Discourse instance URL + # TODO: Change to your Discourse instance URL or leave empty. "discourse": "", # Your Mattermost channel URL + # TODO: Change to your Mattermost channel URL or leave empty. "mattermost": "https://chat.canonical.com/canonical/channels/documentation", # Your Matrix channel URL + # TODO: Change to your Matrix channel URL or leave empty. "matrix": "https://matrix.to/#/#starcraft-development:ubuntu.com", - # Your documentation GitHub repository URL + # Your documentation GitHub repository URL. If set, links for viewing the + # documentation source files and creating GitHub issues are added at the bottom of + # each page. + # TODO: Change to your documentation GitHub repository URL or leave empty. "github_url": "https://github.com/canonical/starbase", # Docs branch in the repo; used in links for viewing the source files "repo_default_branch": "main", @@ -68,16 +90,27 @@ "display_contributors": False, # Required for feedback button "github_issues": "enabled", + # Passes the top-level 'author' value to the theme + "author": author, + # Documentation license information + "license": { + # TODO: Specify your project's license. + # For the name, we recommend using the standard shorthand identifier from + # https://spdx.org/licenses + "name": "LGPL-3.0", + # TODO: Link directly to your project's license statement. + "url": "https://github.com/canonical/starbase/blob/main/LICENSE", + }, } -#html_extra_path = [] - -# Enable the edit button on pages +# TODO: To enable the edit button on pages, change the link to your public repository on +# GitHub or Launchpad. html_theme_options = { "source_edit_link": "https://github.com/canonical/starbase", } -# Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897 +# TODO: If your documentation is hosted on https://documentation.ubuntu.com/, +# uncomment and set to the RTD slug. # slug = "" @@ -94,7 +127,9 @@ # Include `lastmod` dates in the sitemap: # sitemap_show_lastmod = True -# Exclude generated pages from the sitemap: +# TODO: Exclude pages that aren't user-facing from the sitemap (e.g., module pages +# generated by autodoc). +# Pages excluded from the sitemap: sitemap_excludes = [ "404/", "genindex/", @@ -106,16 +141,43 @@ # Template and asset locations # ################################ -html_static_path = ["_static"] -templates_path = ["_templates"] +# html_static_path = ["_static"] +# templates_path = ["_templates"] ############# # Redirects # ############# +# Add redirects to the 'redirects.txt' file +# https://sphinxext-rediraffe.readthedocs.io/en/latest/ + +# To set up redirects in the Read the Docs project dashboard: +# https://docs.readthedocs.io/en/stable/guides/redirects.html + rediraffe_redirects = "redirects.txt" +# Strips '/index.html' from destination URLs when building with 'dirhtml' +rediraffe_dir_only = True + +############################ +# sphinx-llm configuration # +############################ + +# This description is included in llms.txt to provide some initial context for your +# product docs. +# TODO: Add a description in the form "This is the documentation for , +# ". +llms_txt_description = textwrap.dedent( + """\ + This is the documentation for Starbase, a template repository for setting up + and maintaining Starcraft projects. + """ +) + +# The base URL for references built by sphinx-markdown-builder. +if os.environ.get("READTHEDOCS"): + markdown_http_base = html_baseurl ########################### # Link checker exceptions # @@ -135,7 +197,7 @@ ] # Anchor strings to ignore -linkcheck_anchors_ignore = [] +# linkcheck_anchors_ignore = [] # Give linkcheck multiple tries on failure linkcheck_retries = 20 @@ -147,17 +209,18 @@ # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html -# NOTE: The canonical_sphinx extension is required for the starter pack. extensions = [ "canonical_sphinx", "notfound.extension", "sphinx_design", + "sphinx_rerediraffe", # "sphinx_tabs.tabs", # "sphinxcontrib.jquery" "sphinxext.opengraph", # "sphinx_config_options", # "sphinx_contributor_listing", # "sphinx_filtered_toctree", + "sphinx_llm.txt", "sphinx_related_links", "sphinx_roles", "sphinx_terminal", @@ -168,7 +231,6 @@ "sphinx.ext.intersphinx", "sphinx_sitemap", # Custom Craft extensions - "sphinxext.rediraffe", "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.viewcode", @@ -180,19 +242,21 @@ "reuse", ] -# Adds custom CSS files, located under html_static_path -html_css_files = [ - "css/cookie-banner.css" -] +# Adds custom CSS files, located remotely or in 'html_static_path'. +# TODO: Uncomment to enable Google Analytics on public projects. +# html_css_files = [ +# "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", +# ] -# Adds custom JavaScript files, located under html_static_path -html_js_files = [ - "js/bundle.js", -] +# Adds custom JavaScript files, located remotely or in 'html_static_path'. +# TODO: Uncomment to enable Google Analytics on public projects. +# html_js_files = [ +# "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", +# ] -# Specifies a reST snippet to be appended to each .rst file -rst_epilog = """ -""" +# Appends extra markup to the end of every document written in reST +# rst_epilog = """ +# """ # Feedback button at the top; enabled by default # disable_feedback_button = True @@ -215,10 +279,6 @@ :class: vale-ignore """ -# Workaround for https://github.com/canonical/canonical-sphinx/issues/34 -if "discourse_prefix" not in html_context and "discourse" in html_context: - html_context["discourse_prefix"] = f"{html_context['discourse']}/t/" - # Add configuration for intersphinx mapping intersphinx_mapping = { "python": ("https://docs.python.org/3", None), diff --git a/docs/explanation/documentation.rst b/docs/explanation/documentation.rst index 1f1cb15d..13932c81 100644 --- a/docs/explanation/documentation.rst +++ b/docs/explanation/documentation.rst @@ -42,4 +42,4 @@ documents follow: - :external+starflow:ref:`how-to-starcraft-style-guide` - `Canonical Style Guide `__ - `reStructuredText syntax reference - `__ + `__ diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 7af3a688..240f3873 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,3 +1,6 @@ +.. meta:: + :description: The explanatory documentation for Starcraft. These explanations aid in understanding the concepts and relationships of Starcraft as a complete system. + .. _explanation: Explanation diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 2858343a..00e91c16 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -1,3 +1,6 @@ +.. meta:: + :description: The practical, goal-oriented documentation for Starcraft. These guides provide directions for completing tasks and solving problems with Starcraft. + .. _how-to-guides: How-to guides diff --git a/docs/index.rst b/docs/index.rst index f69d32f9..cd727d62 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,6 @@ -.. starcraft documentation root file +.. meta:: + :description: Starcraft is a command-line tool for generating artifacts of many kinds. + Starcraft ========= diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 7f6bd48d..fe1943d0 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,3 +1,6 @@ +.. meta:: + :description: The reference documentation for Starcraft. These references describe the structure and function of the individual components in Starcraft. + .. _reference: Reference diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index e402451c..58108ec1 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -1,10 +1,13 @@ +.. meta:: + :description: The index of release documentation for Starcraft. These release notes summarise the new features, bug fixes, and backwards-incompatible changes in each version. + .. _release-notes: Release notes ============= This page lists the notes for past releases of Starcraft, which summarise new features, -bug fixes and backwards-incompatible changes in each version. It also contains the +bug fixes, and backwards-incompatible changes in each version. It also contains the release and support policies for Starcraft. diff --git a/docs/requirements.txt b/docs/requirements.txt index 7546d515..c8c0535c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,31 +2,33 @@ canonical-sphinx~=0.6 # Extensions previously auto-loaded by canonical-sphinx -myst-parser~=4.0 +myst-parser~=4.0 # v5.0.0 causes version conflicts sphinx-autobuild -sphinx-design -sphinx-notfound-page -sphinx-reredirects -sphinx-tabs -sphinxcontrib-jquery -sphinxext-opengraph +sphinx-design==0.6.1 +sphinx-notfound-page~=1.1 +sphinx-reredirects==0.1.6 +sphinx-tabs~=3.5 +sphinxcontrib-jquery~=4.1 +sphinxext-opengraph~=0.13 +sphinx-rerediraffe>=0.0.3, <1.0.0 # Extra extensions, previously bundled as canonical-sphinx-extensions -sphinx-config-options>=0.1.0 -sphinx-contributor-listing>=0.1.0 -sphinx-filtered-toctree>=0.1.0 -sphinx-related-links>=0.1.2 -sphinx-roles>=0.1.0 -sphinx-terminal>=1.0.2 -sphinx-ubuntu-images>=0.1.0 -sphinx-youtube-links>=0.1.0 +sphinx-config-options~=0.1 +sphinx-contributor-listing~=0.1 +sphinx-filtered-toctree~=0.1 +sphinx-related-links~=0.1 +sphinx-roles~=0.1 +sphinx-terminal~=1.0 +sphinx-ubuntu-images~=0.1 +sphinx-youtube-links~=0.1 # Other dependencies -packaging -sphinxcontrib-svg2pdfconverter[CairoSVG] -sphinx-last-updated-by-git -sphinx-sitemap +packaging~=26.1 +sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1 +sphinx-last-updated-by-git~=0.3 +sphinx-sitemap~=2.9 +sphinx-llm~=0.4 # Vale dependencies rst2html -vale +vale~=3.13 diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 58bb3037..5dbb55a3 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -1,11 +1,15 @@ +.. meta:: + :description: The tutorials for Starcraft. These tutorials are guided lessons that help you develop skills by using Starcraft. + .. _tutorials: Tutorials ========= -If you want to learn the basics from experience, then our tutorials will help you -acquire the necessary competencies from real-life examples with fully reproducible -steps. +The tutorials are guided lessons that help you develop skills by using Starcraft. Each +is self-contained and delivers a working result that marks a learning milestone and is +an opportunity for further exploration. If you're a newcomer to Starcraft, this is the +best way to start. .. toctree:: :hidden: diff --git a/pyproject.toml b/pyproject.toml index 9d544b9a..aa3be959 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,7 +9,7 @@ classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.12", ] -license = "GPL-3.0" +license = "LGPL-3.0" requires-python = ">=3.10" readme = { file = "README.md", content-type = "text/markdown" } @@ -29,33 +29,36 @@ types = [ docs = [ "sphinx-lint~=1.0", "sphinxext-rediraffe==0.3.0", - {include-group = "docs-starter-pack"}, + {include-group = "docs-sphinx-stack"}, ] # We disable the unused but default SP dependencies slated for removal # https://warthogs.atlassian.net/browse/DOCPR-2387 -docs-starter-pack = [ +docs-sphinx-stack = [ "canonical-sphinx~=0.6", - "myst-parser>=4.0.1", - "packaging>=25.0", + "myst-parser~=4.0", + "packaging~=26.1", "rst2html>=2020.7.4", "sphinx-autobuild>=2024.10.3", - # "sphinx-config-options>=0.1.0", - # "sphinx-contributor-listing>=0.1.0", - "sphinx-design>=0.6.1", - # "sphinx-filtered-toctree>=0.1.0", - # "sphinx-last-updated-by-git>=0.3.8", - "sphinx-notfound-page>=1.1.0", - "sphinx-related-links>=0.1.2", - "sphinx-roles>=0.1.0", - "sphinx-sitemap==2.9.0", - # "sphinx-tabs>=3.4.5", - "sphinx-terminal>=1.0.2", - # "sphinx-ubuntu-images>=0.1.0", - # "sphinx-youtube-links>=0.1.0", - "sphinxcontrib-jquery>=4.1", - # "sphinxcontrib-svg2pdfconverter[cairosvg]>=2.0.0", - "sphinxext-opengraph>=0.13.0", - "vale>=3.13.0.0", + # "sphinx-config-options~=0.1", + # "sphinx-contributor-listing~=0.1", + "sphinx-design==0.6.1", + # "sphinx-filtered-toctree~=0.1", + # "sphinx-last-updated-by-git~=0.3", + "sphinx-llm~=0.4", + "sphinx-notfound-page~=1.1", + "sphinx-related-links~=0.1", + # "sphinx-reredirects==0.1.6", + "sphinx-rerediraffe>=0.0.3,<1.0.0", + "sphinx-roles~=0.1", + "sphinx-sitemap~=2.9", + # "sphinx-tabs~=3.5", + "sphinx-terminal~=1.0", + # "sphinx-ubuntu-images~=0.1", + # "sphinx-youtube-links~=0.1", + "sphinxcontrib-jquery~=4.1", + # "sphinxcontrib-svg2pdfconverter[cairosvg]~=2.1", + "sphinxext-opengraph~=0.13", + "vale~=3.13", ] dev = [ "build>=0.7.0", diff --git a/uv.lock b/uv.lock index 84f609d3..11b1a561 100644 --- a/uv.lock +++ b/uv.lock @@ -995,11 +995,11 @@ wheels = [ [[package]] name = "packaging" -version = "26.0" +version = "26.2" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" } +sdist = { url = "https://files.pythonhosted.org/packages/d7/f1/e7a6dd94a8d4a5626c03e4e99c87f241ba9e350cd9e6d75123f992427270/packaging-26.2.tar.gz", hash = "sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661", size = 228134, upload-time = "2026-04-24T20:15:23.917Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" }, + { url = "https://files.pythonhosted.org/packages/df/b2/87e62e8c3e2f4b32e5fe99e0b86d576da1312593b39f47d8ceef365e95ed/packaging-26.2-py3-none-any.whl", hash = "sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e", size = 100195, upload-time = "2026-04-24T20:15:22.081Z" }, ] [[package]] @@ -1462,34 +1462,14 @@ wheels = [ name = "sphinx-design" version = "0.6.1" source = { registry = "https://pypi.org/simple" } -resolution-markers = [ - "python_full_version < '3.11'", -] dependencies = [ - { name = "sphinx", marker = "python_full_version < '3.11'" }, + { name = "sphinx" }, ] sdist = { url = "https://files.pythonhosted.org/packages/2b/69/b34e0cb5336f09c6866d53b4a19d76c227cdec1bbc7ac4de63ca7d58c9c7/sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632", size = 2193689, upload-time = "2024-08-02T13:48:44.277Z" } wheels = [ { url = "https://files.pythonhosted.org/packages/c6/43/65c0acbd8cc6f50195a3a1fc195c404988b15c67090e73c7a41a9f57d6bd/sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c", size = 2215338, upload-time = "2024-08-02T13:48:42.106Z" }, ] -[[package]] -name = "sphinx-design" -version = "0.7.0" -source = { registry = "https://pypi.org/simple" } -resolution-markers = [ - "python_full_version >= '3.15'", - "python_full_version >= '3.12' and python_full_version < '3.15'", - "python_full_version == '3.11.*'", -] -dependencies = [ - { name = "sphinx", marker = "python_full_version >= '3.11'" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/13/7b/804f311da4663a4aecc6cf7abd83443f3d4ded970826d0c958edc77d4527/sphinx_design-0.7.0.tar.gz", hash = "sha256:d2a3f5b19c24b916adb52f97c5f00efab4009ca337812001109084a740ec9b7a", size = 2203582, upload-time = "2026-01-19T13:12:53.297Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/30/cf/45dd359f6ca0c3762ce0490f681da242f0530c49c81050c035c016bfdd3a/sphinx_design-0.7.0-py3-none-any.whl", hash = "sha256:f82bf179951d58f55dca78ab3706aeafa496b741a91b1911d371441127d64282", size = 2220350, upload-time = "2026-01-19T13:12:51.077Z" }, -] - [[package]] name = "sphinx-last-updated-by-git" version = "0.3.8" @@ -1515,6 +1495,33 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/c0/62/f29a2988ff706ac01d3c63d0b4cc4ed62d2c83b447916e0317790ca156cf/sphinx_lint-1.0.2-py3-none-any.whl", hash = "sha256:edcd0fa4d916386c5a3ef7ef0f5136f0bb4a15feefc83c1068ba15bc16eec652", size = 20670, upload-time = "2025-11-19T08:28:10.656Z" }, ] +[[package]] +name = "sphinx-llm" +version = "0.4.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, + { name = "sphinx-markdown-builder" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/59/23/fe184bf9c6761c2cd04dc5b5456b717f626143663a3004f628636a2f7b0e/sphinx_llm-0.4.1.tar.gz", hash = "sha256:0789185dcbbecc00b5e25aa3db6342b98dad6a9def96088a9e50fa0203fda090", size = 280250, upload-time = "2026-04-02T09:09:18.881Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/31/2b/a54c49b42b25a6eb6039daf882f06488812c28e32734e944b2f7b6f82554/sphinx_llm-0.4.1-py3-none-any.whl", hash = "sha256:d7c8ee2a6335636b628ea2b26cd1e1dee1f0cf9c40fe51b20f201af1c05b95f5", size = 28453, upload-time = "2026-04-02T09:09:17.632Z" }, +] + +[[package]] +name = "sphinx-markdown-builder" +version = "0.6.10" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "sphinx" }, + { name = "tabulate" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a0/58/0b7b9a7d071140b3705885d51932e8b62f520388c2772e4952189971727b/sphinx_markdown_builder-0.6.10.tar.gz", hash = "sha256:cd5acf88d52ea0146a712fd557404f10326dff3428a78ba928e59b1727fd4a86", size = 22688, upload-time = "2026-03-11T10:56:57.639Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c2/8f/9fecf3d081d5cd49eff83a17b9fef50ed741e6223ab3bb906de4ab0068f9/sphinx_markdown_builder-0.6.10-py3-none-any.whl", hash = "sha256:16d86738b9ac69fcbc86e373c31c6402c30af1fa8d98d0f62cc5f38bfe5fc26e", size = 16700, upload-time = "2026-03-11T10:56:56.135Z" }, +] + [[package]] name = "sphinx-notfound-page" version = "1.1.0" @@ -1542,6 +1549,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/3d/bd/6971dde17d8f1446a1b52d22d3b937df8f7fd380b94d109c3d9e3f2bfd62/sphinx_related_links-0.1.2-py3-none-any.whl", hash = "sha256:0f894cff31f330aa0fbbfb2d6cccc0bc07153a56925427d9f3dc4a1d9b0e08eb", size = 19873, upload-time = "2025-12-15T19:09:41.008Z" }, ] +[[package]] +name = "sphinx-rerediraffe" +version = "0.0.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/1a/6e/1909520b53151bc43073ac4c1835cbef591ec1cce11bc9407d45f0d8002a/sphinx_rerediraffe-0.0.4.tar.gz", hash = "sha256:b2053057bfc2dd79c20f986322e35c7ba4a40714ebaf2b075c860432fb0cca84", size = 24143, upload-time = "2026-05-26T18:00:34.616Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/03/36/676ea0d96745d1f4fe87ff9a2d9fc1adcb9249f0b329928d1173ddff7194/sphinx_rerediraffe-0.0.4-py3-none-any.whl", hash = "sha256:7b39d08c3f34439bd3cb486c286e77672d37c8eb8fe39dd4d91a3db62aebcc99", size = 8100, upload-time = "2026-05-26T18:00:32.518Z" }, +] + [[package]] name = "sphinx-roles" version = "0.1.0" @@ -1694,11 +1713,12 @@ docs = [ { name = "rst2html" }, { name = "sphinx-autobuild", version = "2024.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autobuild", version = "2025.8.25", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-design" }, { name = "sphinx-lint" }, + { name = "sphinx-llm" }, { name = "sphinx-notfound-page" }, { name = "sphinx-related-links" }, + { name = "sphinx-rerediraffe" }, { name = "sphinx-roles" }, { name = "sphinx-sitemap" }, { name = "sphinx-terminal" }, @@ -1707,17 +1727,18 @@ docs = [ { name = "sphinxext-rediraffe" }, { name = "vale" }, ] -docs-starter-pack = [ +docs-sphinx-stack = [ { name = "canonical-sphinx" }, { name = "myst-parser" }, { name = "packaging" }, { name = "rst2html" }, { name = "sphinx-autobuild", version = "2024.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autobuild", version = "2025.8.25", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-design" }, + { name = "sphinx-llm" }, { name = "sphinx-notfound-page" }, { name = "sphinx-related-links" }, + { name = "sphinx-rerediraffe" }, { name = "sphinx-roles" }, { name = "sphinx-sitemap" }, { name = "sphinx-terminal" }, @@ -1752,37 +1773,41 @@ dev = [ ] docs = [ { name = "canonical-sphinx", specifier = "~=0.6" }, - { name = "myst-parser", specifier = ">=4.0.1" }, - { name = "packaging", specifier = ">=25.0" }, + { name = "myst-parser", specifier = "~=4.0" }, + { name = "packaging", specifier = "~=26.1" }, { name = "rst2html", specifier = ">=2020.7.4" }, { name = "sphinx-autobuild", specifier = ">=2024.10.3" }, - { name = "sphinx-design", specifier = ">=0.6.1" }, + { name = "sphinx-design", specifier = "==0.6.1" }, { name = "sphinx-lint", specifier = "~=1.0" }, - { name = "sphinx-notfound-page", specifier = ">=1.1.0" }, - { name = "sphinx-related-links", specifier = ">=0.1.2" }, - { name = "sphinx-roles", specifier = ">=0.1.0" }, - { name = "sphinx-sitemap", specifier = "==2.9.0" }, - { name = "sphinx-terminal", specifier = ">=1.0.2" }, - { name = "sphinxcontrib-jquery", specifier = ">=4.1" }, - { name = "sphinxext-opengraph", specifier = ">=0.13.0" }, + { name = "sphinx-llm", specifier = "~=0.4" }, + { name = "sphinx-notfound-page", specifier = "~=1.1" }, + { name = "sphinx-related-links", specifier = "~=0.1" }, + { name = "sphinx-rerediraffe", specifier = ">=0.0.3,<1.0.0" }, + { name = "sphinx-roles", specifier = "~=0.1" }, + { name = "sphinx-sitemap", specifier = "~=2.9" }, + { name = "sphinx-terminal", specifier = "~=1.0" }, + { name = "sphinxcontrib-jquery", specifier = "~=4.1" }, + { name = "sphinxext-opengraph", specifier = "~=0.13" }, { name = "sphinxext-rediraffe", specifier = "==0.3.0" }, - { name = "vale", specifier = ">=3.13.0.0" }, + { name = "vale", specifier = "~=3.13" }, ] -docs-starter-pack = [ +docs-sphinx-stack = [ { name = "canonical-sphinx", specifier = "~=0.6" }, - { name = "myst-parser", specifier = ">=4.0.1" }, - { name = "packaging", specifier = ">=25.0" }, + { name = "myst-parser", specifier = "~=4.0" }, + { name = "packaging", specifier = "~=26.1" }, { name = "rst2html", specifier = ">=2020.7.4" }, { name = "sphinx-autobuild", specifier = ">=2024.10.3" }, - { name = "sphinx-design", specifier = ">=0.6.1" }, - { name = "sphinx-notfound-page", specifier = ">=1.1.0" }, - { name = "sphinx-related-links", specifier = ">=0.1.2" }, - { name = "sphinx-roles", specifier = ">=0.1.0" }, - { name = "sphinx-sitemap", specifier = "==2.9.0" }, - { name = "sphinx-terminal", specifier = ">=1.0.2" }, - { name = "sphinxcontrib-jquery", specifier = ">=4.1" }, - { name = "sphinxext-opengraph", specifier = ">=0.13.0" }, - { name = "vale", specifier = ">=3.13.0.0" }, + { name = "sphinx-design", specifier = "==0.6.1" }, + { name = "sphinx-llm", specifier = "~=0.4" }, + { name = "sphinx-notfound-page", specifier = "~=1.1" }, + { name = "sphinx-related-links", specifier = "~=0.1" }, + { name = "sphinx-rerediraffe", specifier = ">=0.0.3,<1.0.0" }, + { name = "sphinx-roles", specifier = "~=0.1" }, + { name = "sphinx-sitemap", specifier = "~=2.9" }, + { name = "sphinx-terminal", specifier = "~=1.0" }, + { name = "sphinxcontrib-jquery", specifier = "~=4.1" }, + { name = "sphinxext-opengraph", specifier = "~=0.13" }, + { name = "vale", specifier = "~=3.13" }, ] lint = [] tics = [ @@ -1809,6 +1834,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/81/0d/13d1d239a25cbfb19e740db83143e95c772a1fe10202dda4b76792b114dd/starlette-0.52.1-py3-none-any.whl", hash = "sha256:0029d43eb3d273bc4f83a08720b4912ea4b071087a3b48db01b7c839f7954d74", size = 74272, upload-time = "2026-01-18T13:34:09.188Z" }, ] +[[package]] +name = "tabulate" +version = "0.10.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/46/58/8c37dea7bbf769b20d58e7ace7e5edfe65b849442b00ffcdd56be88697c6/tabulate-0.10.0.tar.gz", hash = "sha256:e2cfde8f79420f6deeffdeda9aaec3b6bc5abce947655d17ac662b126e48a60d", size = 91754, upload-time = "2026-03-04T18:55:34.402Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/99/55/db07de81b5c630da5cbf5c7df646580ca26dfaefa593667fc6f2fe016d2e/tabulate-0.10.0-py3-none-any.whl", hash = "sha256:f0b0622e567335c8fabaaa659f1b33bcb6ddfe2e496071b743aa113f8774f2d3", size = 39814, upload-time = "2026-03-04T18:55:31.284Z" }, +] + [[package]] name = "tomli" version = "2.4.0"