test: 1.3.0 migration

.github/.jira_sync_config.yaml

@@ -0,0 +1,59 @@
+settings:
+    # Jira project key to create the issue in
+  jira_project_key: "ROCKS"
+
+  # Dictionary mapping GitHub issue status to Jira issue status
+  status_mapping:
+    opened: Untriaged
+    closed: done
+    # (Optional) Use different status for GitHub issues closed as not planned (instead of closed as
+    # completed)
+    # https://github.blog/changelog/2022-03-10-the-new-github-issues-march-10th-update/#%F0%9F%95%B5%F0%9F%8F%BD%E2%99%80%EF%B8%8F-issue-closed-reasons
+    # If not specified, `closed` status will be used.
+    not_planned: rejected
+
+  # (Optional) Jira project components that should be attached to the created issue
+  # Component names are case-sensitive
+  components:
+
+  # (Optional) GitHub labels. Only issues with one of those labels will be synchronized.
+  # If not specified, all issues will be synchronized
+  labels:
+
+  # (Optional) (Default: false) Add a new comment in GitHub with a link to Jira created issue
+  add_gh_comment: false
+
+  # (Optional) (Default: false) Add a 'synced-to-jira' label to newly created issues once a
+  # corresponding ticket is successfully created in Jira.
+  # This label serves as confirmation that the issue sync process was completed successfully.
+  add_gh_synced_label: false
+
+  # (Optional) (Default: true) Synchronize issue description from GitHub to Jira
+  sync_description: true
+
+  # (Optional) (Default: true) Synchronize comments from GitHub to Jira
+  sync_comments: true
+
+  # (Optional) (Default: None) Parent Epic key to link the issue to
+  epic_key: "ROCKS-2724"
+
+  # (Optional) Dictionary mapping GitHub issue labels to Jira issue types. 
+  # If label on the issue is not in specified list, this issue will be created as a Bug
+  label_mapping:
+    enhancement: Task
+
+  # (Optional) JIRA issue's summary
+  # This field can be used to customize the JIRA issue's summary (title).
+  # The value of the field will be passed to the python
+  # format() method to generate the JIRA summary. The GH issue
+  # variable will be captured in the format() method so that users can
+  # use GH issue attribute's values to build the JIRA summary.
+  # See GH issue definition :
+  # https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28
+  #
+  # Examples:
+  # to use fixed title "github issue": "github issue"
+  # to use GH issue title: "{issue.title}"
+  # to add prefix "[GitHub]" : "[GitHub] {issue.title}"
+  # to add user in the title (between square brackets): "[{issue.user.login}] {issue.title}"
+  summary: "[GitHub] {issue.title}"

README.md

@@ -61,6 +61,31 @@ After submitting a pull request, your changes will be reviewed by a project
 maintainer.
 
 
+### Custom page meta descriptions
+
+The meta description provides a summary of the page. Search engines often reuse this for the search result’s snippet.
+
+All **new** pages must include a meta description. To set custom HTML meta descriptions in MyST-MD, use front matter at the top of the document as shown below:
+
+```
+---
+myst:
+  html_meta:
+    description: Your description of the page.
+---
+```
+
+Please observe the following guidelines:
+
+- Use a maximum of 160 characters.
+- Summarize the content of the page, where possible.
+- Keep the language simple, avoid unnecessary adverbs or adjectives.
+- Use an informative tone, frame sentences in terms of actions and facts.
+- Use the tool name and page-specific terminology that users are likely to use when searching for information. 
+- Place key terms near the start.
+- Don’t include key terms that aren’t on the page.
+
+
 ### Get help
 
 If you are a new contributor to documentation in general and would like some

docs/.custom_wordlist.txt

@@ -21,6 +21,7 @@ armor
 armored
 basename
 behavior
+binutils
 chiseled
 conffiles
 config
@@ -33,6 +34,7 @@ fips
 http
 https
 initialize
+jaotc
 jsonwall
 libs
 linters
@@ -48,6 +50,9 @@ subcommand
 subcommands
 symlink
 symlinks
+timezones
 ubuntu
+unopinionated
 whitespace
 yaml
+Canonical's

docs/Makefile

@@ -4,30 +4,34 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXDIR       = .sphinx
-SPHINXOPTS      ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
-SPHINXBUILD     ?= $(VENVDIR)/bin/sphinx-build
-SOURCEDIR       = .
-BUILDDIR        = _build
-VENVDIR         = $(SPHINXDIR)/venv
-PA11Y           = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
-VENV            = $(VENVDIR)/bin/activate
-TARGET          = *
-METRICSDIR      = $(SOURCEDIR)/.sphinx/metrics
-REQPDFPACKS     = 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
-CONFIRM_SUDO    ?= N
-VALE_CONFIG     = $(SPHINXDIR)/vale.ini
-VALEDIR         = $(SPHINXDIR)/venv/lib/python*/site-packages/vale
-VOCAB_CANONICAL = $(SPHINXDIR)/styles/config/vocabularies/Canonical
-SPHINX_HOST     ?= 127.0.0.1
-SPHINX_PORT     ?= 8000
+SPHINXDIR         = .sphinx
+SPHINXOPTS        ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
+SPHINXBUILD       ?= $(VENVDIR)/bin/sphinx-build
+SOURCEDIR         = .
+BUILDDIR          = _build
+VENVDIR           = $(SPHINXDIR)/venv
+PA11Y             = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+VENV              = $(VENVDIR)/bin/activate
+TARGET            = *
+METRICSDIR        = $(SOURCEDIR)/.sphinx/metrics
+REQPDFPACKS       = 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
+CONFIRM_SUDO      ?= N
+VALE_CONFIG       = $(SPHINXDIR)/vale.ini
+VALEDIR           = $(SPHINXDIR)/venv/lib/python*/site-packages/vale
+VOCAB_CANONICAL   = $(SPHINXDIR)/styles/config/vocabularies/Canonical
+SPHINX_HOST       ?= 127.0.0.1
+SPHINX_PORT       ?= 8000
+
+# Sphinx options with sphinx-llm artifact generation disabled (for builds where llms.txt is not needed):
+SPHINX_OPTS_NOLLM = $(SPHINXOPTS) -D llms_txt_enabled=0
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@echo
 	@echo "-------------------------------------------------------------"
 	@echo "* watch, build and serve the documentation:  make run"
-	@echo "* only build:                                make html"
+	@echo "* only build (full, with LLM artifacts):     make html"
+	@echo "* only build (without LLM artifacts):        make html-lite"
 	@echo "* only serve:                                make serve"
 	@echo "* clean built doc files:                     make clean-doc"
 	@echo "* clean full environment:                    make clean"
@@ -44,7 +48,7 @@ help:
 	@echo "-------------------------------------------------------------"
 	@echo
 
-.PHONY: help full‑help html epub pdf linkcheck spelling spellcheck woke \
+.PHONY: help full‑help html html-lite epub pdf linkcheck spelling spellcheck woke \
         vale pa11y run serve install pa11y‑install   \
         vale‑install pdf‑prep pdf‑prep‑force clean clean‑doc allmetrics \
         update lint-md
@@ -85,6 +89,9 @@ run: install
 html: install
 	. $(VENV); $(SPHINXBUILD) --fail-on-warning --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
 
+html-lite: install
+	. $(VENV); $(SPHINXBUILD) --fail-on-warning --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINX_OPTS_NOLLM)
+
 epub: install
 	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)