Merge pull request #2869 from canonical/docs

bring docs to docs-devel

.github/labeler.yml

@@ -0,0 +1,3 @@
+# Add "docs" label to any PR against this branch
+docs:
+- '**'

.github/workflows/automatic-doc-checks.yaml

@@ -0,0 +1,16 @@
+name: Main Documentation Checks
+
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: '.'

.github/workflows/ci-base.yaml

@@ -20,4 +20,4 @@ jobs:
       - name: Install docs environment
         run: make install
       - name: Build docs
-        run: make build
+        run: make html

.github/workflows/label-docs.yaml

@@ -0,0 +1,17 @@
+name: "Pull Request Labeler"
+
+on:
+- pull_request_target
+
+jobs:
+  docs:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/labeler@v4
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        dot: true
+

.readthedocs.yaml

@@ -1,13 +1,15 @@
 version: 2
 
 sphinx:
-   configuration: docs/conf.py
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
 
 build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
 
 python:
-   install:
-   - requirements: docs-requirements.txt
+  install:
+  - requirements: docs-requirements.txt

CONTRIBUTING.md

@@ -13,6 +13,7 @@ from the architecture of the project to how you should test any code changes.
 * [How to release a new version](./dev-docs/howtoguides/how_to_release_a_new_version_of_ua.md)
 * [How to use the contract staging environment](./dev-docs/howtoguides/use_staging_environment.md)
 * [How to use the magic attach endpoints](./dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md)
+* [How to spellcheck messages](./dev-docs/howtoguides/spellcheck.md)
 
 ### Reference
 
@@ -29,7 +30,10 @@ from the architecture of the project to how you should test any code changes.
 ### Explanation
 
 * [How auto-attach works](./dev-docs/explanations/how_auto_attach_works.md)
+* [Translations](./dev-docs/explanations/translations.md)
+* [Policy on string changes](./dev-docs/explanations/string_changes_policy.md)
 
 ### Documentation
 
-* [Documentation guide](./dev-docs/devdocs_styleguide.md)
+* [How to contribute to our documentation](./dev-docs/documentation/contribute_docs.md)
+* [Our style guide](./dev-docs/documentation/styleguide.md)

Makefile

@@ -1,23 +1,85 @@
-VENV          	= .sphinx/venv
-ACTIVATE_VENV	= $(VENV)/bin/activate
-SOURCEDIR     	= docs/
-BUILDDIR     	= docs/build/
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SPHINXDIR     = .sphinx
+SOURCEDIR     = docs/
+BUILDDIR      = docs/build/
+VENVDIR       = $(SPHINXDIR)/venv
+VENV          = $(VENVDIR)/bin/activate
 
-install:
-	python3 -m venv $(VENV)
-	. $(ACTIVATE_VENV); pip install --upgrade -r docs-requirements.txt
+.PHONY: help woke-install install run html epub serve clean clean-doc \
+        spelling linkcheck woke Makefile
 
-build:
-	. $(ACTIVATE_VENV); sphinx-build -W -b html $(SOURCEDIR) $(BUILDDIR)
+# Put it first so that "make" without argument is like "make help".
+help: $(VENVDIR)
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-run:
-	. $(ACTIVATE_VENV); sphinx-autobuild $(SOURCEDIR) $(BUILDDIR)
+docs-requirements.txt:
+	test -f docs-requirements.txt
 
-serve:
-	python3 -m http.server --directory $(BUILDDIR) 8000
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR): docs-requirements.txt
+	@echo "... setting up virtualenv"
+	python3 -m venv $(VENVDIR)
+	. $(VENV); pip install --require-virtualenv \
+	    --upgrade -r docs-requirements.txt \
+            --log $(VENVDIR)/pip_install.log
+	@test ! -f $(VENVDIR)/pip_list.txt || \
+            mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
+	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
+	@echo "\n" \
+        "--------------------------------------------------------------- \n" \
+        "* watch, build and serve the documentation: make run \n" \
+        "* only build: make html \n" \
+        "* only serve: make serve \n" \
+        "* clean built doc files: make clean-doc \n" \
+        "* clean full environment: make clean \n" \
+        "* check links: make linkcheck \n" \
+        "* check spelling: make spelling \n" \
+        "* check inclusive language: make woke \n" \
+        "* other possible targets: make <press TAB twice> \n" \
+        "--------------------------------------------------------------- \n"
+	@touch $(VENVDIR)
 
-clean:
-	rm -rf $(VENV)
-	rm -rf $(BUILDDIR)
+woke-install:
+	@type woke >/dev/null 2>&1 || \
+            { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
 
-.PHONY: install build run serve clean
+install: $(VENVDIR) woke-install
+
+run: install
+	. $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS)
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS)
+
+serve: html
+	cd "$(BUILDDIR)"; python3 -m http.server 8000
+
+clean: clean-doc
+	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf .sphinx/.doctrees
+
+clean-doc:
+	git clean -fx "$(BUILDDIR)"
+
+spelling: html
+	. $(VENV) ; python3 -m pyspelling -c spellingcheck.yaml
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+woke: woke-install
+	woke *.rst **/*.rst *.md **/*.md --exit-1-on-failure \
+	    -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -6,7 +6,13 @@
   Ubuntu Pro Client Documentation
 </h1>
 
-The Ubuntu Pro Client (`pro`) is the official tool to enable Canonical offerings on your
-system.
+The Ubuntu Pro Client (`pro`) is the official tool to enable Canonical
+offerings on your system.
+
+This branch (`docs`) contains the files used to build our documentation,
+which is hosted at [Read the Docs](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/).
+
+For details of how you can contribute, including instructions on how to build
+a local copy of the documentation, you can read
+[our contributing guide](https://github.com/canonical/ubuntu-pro-client/blob/docs/CONTRIBUTING.md).
 
-This branch contains the files used to build https://canonical-ubuntu-pro-client.readthedocs-hosted.com/

custom_wordlist.txt

@@ -0,0 +1,137 @@
+AdditionalData
+airgapped
+Airgapping
+amd
+anbox
+Anbox
+aptnews
+AptUpgradeData
+Args
+armhf
+AttachData
+aws
+backport
+benchmarking
+bool
+boolean
+BuildKit
+Center
+cis
+CIS
+cli
+conf
+conffile
+config
+cron
+CTRL
+cve
+CVE
+CVEAPIFixExecuteResult
+CVEFixPlanResult
+cves
+CVEs
+DISA
+Dockerfile
+dpkg
+eal
+EAL
+el
+EnableData
+EnabledService
+enablement
+esm
+ESM
+FailedUpgrade
+fips
+FIPS
+firewalled
+Firewalled
+FixExecuteError
+FixExecuteResult
+FixExecuteUSNResult
+FixPlanError
+FixPlanResult
+FixPlanStep
+FixPlanUSNResult
+FixPlanWarning
+gapping
+gcp
+GCP
+googleaf
+honor
+honored
+hostname
+html
+https
+init
+internetless
+json
+latencies
+Libera
+livepatch
+Livepatch
+LivepatchCVEObject
+Livepatches
+LTS
+lxd
+LXD
+Mantic
+motd
+MOTD
+Multipass
+NoOp
+NoOpAlreadyFixed
+NoOpData
+NoOpLivepatchFixData
+num
+PackageCannotBeInstalledData
+PackageSummary
+PEM
+PID
+powerpc
+PPA
+PPAs
+ppc
+pradyunsg
+prem
+programmatically
+proxying
+py
+pycurl
+realtime
+riscv
+ros
+ROS
+runtime
+Runtime
+SaaS
+SecurityIssueNotFixedData
+Specialty
+SRU
+SSL
+SSO
+STIG
+str
+subcommand
+subcommands
+TBD
+telco
+TLS
+uaclient
+ubuntu
+un
+unparsed
+UpdateInfo
+UpdateSummary
+UpgradedPackage
+usg
+USG
+usn
+usns
+USNAPIFixExecuteResult
+USNFixPlanResult
+USNs
+usr
+VMs
+Xenial
+yaml