diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml index d1519e1..479ebcb 100644 --- a/.github/workflows/automatic-doc-checks.yml +++ b/.github/workflows/automatic-doc-checks.yml @@ -1,11 +1,16 @@ -name: Main Documentation Checks +# +name: Automatic doc checks on: push: - branches: [main] + branches: [ main ] pull_request: - # Manual trigger + paths: + - 'docs/**' # Only run on changes to the docs directory + workflow_dispatch: + # Manual trigger + concurrency: group: ${{ github.workflow }}-${{ github.ref }} @@ -16,3 +21,4 @@ jobs: uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main with: working-directory: "docs" + fetch-depth: 0 diff --git a/.github/workflows/markdown-style-checks.yml b/.github/workflows/markdown-style-checks.yml index 85e0f4a..e0de019 100644 --- a/.github/workflows/markdown-style-checks.yml +++ b/.github/workflows/markdown-style-checks.yml @@ -1,21 +1,24 @@ -name: "Linter for Markdown" +name: Markdown style checks on: push: branches: - - main + - main + paths: + - 'docs/**' # Only run on changes to the docs directory pull_request: branches: - - '*' + - '*' + paths: + - 'docs/**' # Only run on changes to the docs directory jobs: markdown-lint: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - uses: DavidAnson/markdownlint-cli2-action@v16 - with: - config: "docs/.sphinx/.markdownlint.json" - working-directory: "docs" + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: DavidAnson/markdownlint-cli2-action@v16 + with: + config: "docs/.sphinx/.markdownlint.json" diff --git a/.github/workflows/periodic-style-checks.yml b/.github/workflows/periodic-style-checks.yml deleted file mode 100644 index ad8c895..0000000 --- a/.github/workflows/periodic-style-checks.yml +++ /dev/null @@ -1,19 +0,0 @@ -name: Periodic Style Checks - -on: - schedule: - - cron: "0 1 * * 4" # Runs at 01:00 AM on every Wednesday - -jobs: - vale: - name: Style checker - runs-on: ubuntu-22.04 - defaults: - run: - shell: bash - working-directory: "docs" - steps: - - uses: actions/checkout@v4 - - name: Run vale - run: | - make vale diff --git a/.github/workflows/sphinx-python-dependency-build-checks.yml b/.github/workflows/sphinx-python-dependency-build-checks.yml deleted file mode 100644 index 8a7d3c6..0000000 --- a/.github/workflows/sphinx-python-dependency-build-checks.yml +++ /dev/null @@ -1,48 +0,0 @@ -# The purpose of this workflow file is to confirm that the Sphinx -# virtual environment can be built from source, consequently documenting -# the packages required in the build environment to do that. -# -# This is needed because some projects embeds the documentation into built -# artifacts which involves rendering the documentation on the target -# architecture. -# -# Depending on the architecture, pip may or may not have already built wheels -# available, and as such we need to make sure building wheels from source can -# succeed. -name: Check and document build requirements for Sphinx venv -on: - - push - - pull_request - - workflow_dispatch - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - build: - name: build - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install dependencies - run: | - set -ex - sudo apt -y install \ - cargo \ - libpython3-dev \ - libxml2-dev \ - libxslt1-dev \ - make \ - python3-venv \ - rustc - - name: Build Sphinx venv - working-directory: "docs" - run: | - set -ex - make -f Makefile.sp \ - sp-install \ - PIPOPTS="--no-binary :all:" \ - || ( cat .sphinx/venv/pip_install.log && exit 1 ) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index c539e64..12d2357 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,36 +1,75 @@ +# Leave a blank line at the end of this file to support concatenation abi +ack'd +Ack'd +Ack's +Acked amd backport -backports backported +backports BugLink +cjk +commit's config configs +creativecommons cryptographically -customisation customizations CVE debian Dev +devel Devel +DeveloperApplicationTemplate dkms +DKMSUploadApplication +DMB +dvipng eol ESM filebug +fonts +forgejo +freefont Gitea +github +GPG +gyre https hwe IoT +irc Kconfig +KernelGitGuide +KernelTeam +KernelUpdates +kustom +lang +latexmk +libera +lifecycle linux +LuisHenriques manpages Mantic metapackage +mofed +motu +Nack'd oem +otf +packageset +PaoloPisati patchset +PerPackageUploaderApplication +plantuml PPAs +PPUApplicationTemplate +repo respin respins +sa selftests sha snapcraft @@ -39,8 +78,20 @@ src sru SRUs Tahr +tex +texlive +TOC +txt ubuntu UC uncomment +Unported +uploaders +upstreamed +utils +WCAG +wordlist Xenial -Xerus \ No newline at end of file +Xerus +xetex +xindy diff --git a/docs/.gitignore b/docs/.gitignore index 468749d..bf16e0d 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,17 +1,25 @@ - -# Starter pack rules start here -/*env*/ +# Environment +*env*/ .sphinx/venv/ + +# Sphinx .sphinx/warnings.txt .sphinx/.wordlist.dic .sphinx/.doctrees/ .sphinx/node_modules/ -package*.json + +# Vale +.sphinx/styles/* +.sphinx/vale.ini + +# Build outputs _build + +# Node.js +package*.json + +# Unrelated cache and config files .DS_Store __pycache__ .idea/ .vscode/ -.sphinx/styles/* -.sphinx/vale.ini -sp-docs/_build \ No newline at end of file diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml index f170b00..d98ecb1 100644 --- a/docs/.readthedocs.yaml +++ b/docs/.readthedocs.yaml @@ -12,7 +12,17 @@ build: python: "3.11" jobs: pre_install: - - git fetch --unshallow || true + - git fetch --unshallow || true + post_checkout: + # Cancel building pull requests when there aren't changed in the docs directory. + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- 'docs/' '.readthedocs.yaml'; + then + exit 183; + fi # Build documentation in the docs/ directory with Sphinx sphinx: @@ -22,9 +32,9 @@ sphinx: # If using Sphinx, optionally build your docs in additional formats such as PDF formats: - - pdf +- pdf # Optionally declare the Python requirements required to build your docs python: install: - - requirements: docs/.sphinx/requirements.txt + - requirements: docs/.sphinx/requirements.txt diff --git a/docs/.sphinx/.markdownlint.json b/docs/.sphinx/.markdownlint.json index 8aafaf6..f42753f 100644 --- a/docs/.sphinx/.markdownlint.json +++ b/docs/.sphinx/.markdownlint.json @@ -1,13 +1,24 @@ { "default": false, - "MD003": { "style": "atx" }, - "MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 150}, + "MD003": { + "style": "atx" + }, + "MD013": { + "code_blocks": false, + "tables": false, + "stern": true, + "line_length": 150 + }, "MD014": true, "MD018": true, "MD022": true, "MD023": true, - "MD026": { "punctuation": ".,;。，；"}, - "MD031": { "list_items": false}, + "MD026": { + "punctuation": ".,;。，；" + }, + "MD031": { + "list_items": false + }, "MD032": true, "MD035": true, "MD042": true, diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/.sphinx/.pre-commit-config.yaml new file mode 100644 index 0000000..07e0b48 --- /dev/null +++ b/docs/.sphinx/.pre-commit-config.yaml @@ -0,0 +1,23 @@ +repos: + - repo: local + hooks: + - id: make-spelling + name: Run make spelling + entry: make -C docs spelling + language: system + pass_filenames: false + files: ^docs/.*\.(rst|md|txt)$ + + - id: make-linkcheck + name: Run make linkcheck + entry: make -C docs linkcheck + language: system + pass_filenames: false + files: ^docs/.*\.(rst|md|txt)$ + + - id: make-woke + name: Run make woke + entry: make -C docs woke + language: system + pass_filenames: false + files: ^docs/.*\.(rst|md|txt)$ diff --git a/docs/.sphinx/_static/css/pdf.css b/docs/.sphinx/_static/css/pdf.css deleted file mode 100644 index f9e28dd..0000000 --- a/docs/.sphinx/_static/css/pdf.css +++ /dev/null @@ -1,15 +0,0 @@ -/* Only relevant for specific PDF generation issues */ - -.rubric>.hclass2 { - display: block; - font-size: 2em; - border-radius: .5rem; - font-weight: 300; - line-height: 1.25; - margin-top: 1.75rem; - margin-right: -0.5rem; - margin-bottom: 0.5rem; - margin-left: -0.5rem; - padding-left: .5rem; - padding-right: .5rem; -} \ No newline at end of file diff --git a/docs/.sphinx/_static/favicon.png b/docs/.sphinx/_static/favicon.png deleted file mode 100644 index 7f175e4..0000000 Binary files a/docs/.sphinx/_static/favicon.png and /dev/null differ diff --git a/docs/.sphinx/_static/project_specific.css b/docs/.sphinx/_static/project_specific.css new file mode 100644 index 0000000..e69de29 diff --git a/docs/.sphinx/_static/tag.png b/docs/.sphinx/_static/tag.png deleted file mode 100644 index f6f6e5a..0000000 Binary files a/docs/.sphinx/_static/tag.png and /dev/null differ diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html deleted file mode 100644 index f9848fe..0000000 --- a/docs/.sphinx/_templates/header.html +++ /dev/null @@ -1,52 +0,0 @@ - \ No newline at end of file diff --git a/docs/.sphinx/fonts/LICENCE.txt b/docs/.sphinx/fonts/LICENCE.txt deleted file mode 100644 index ae78a8f..0000000 --- a/docs/.sphinx/fonts/LICENCE.txt +++ /dev/null @@ -1,96 +0,0 @@ -------------------------------- -UBUNTU FONT LICENCE Version 1.0 -------------------------------- - -PREAMBLE -This licence allows the licensed fonts to be used, studied, modified and -redistributed freely. The fonts, including any derivative works, can be -bundled, embedded, and redistributed provided the terms of this licence -are met. The fonts and derivatives, however, cannot be released under -any other licence. The requirement for fonts to remain under this -licence does not require any document created using the fonts or their -derivatives to be published under this licence, as long as the primary -purpose of the document is not to be a vehicle for the distribution of -the fonts. - -DEFINITIONS -"Font Software" refers to the set of files released by the Copyright -Holder(s) under this licence and clearly marked as such. This may -include source files, build scripts and documentation. - -"Original Version" refers to the collection of Font Software components -as received under this licence. - -"Modified Version" refers to any derivative made by adding to, deleting, -or substituting -- in part or in whole -- any of the components of the -Original Version, by changing formats or by porting the Font Software to -a new environment. - -"Copyright Holder(s)" refers to all individuals and companies who have a -copyright ownership of the Font Software. - -"Substantially Changed" refers to Modified Versions which can be easily -identified as dissimilar to the Font Software by users of the Font -Software comparing the Original Version with the Modified Version. - -To "Propagate" a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification and with or without charging -a redistribution fee), making available to the public, and in some -countries other activities as well. - -PERMISSION & CONDITIONS -This licence does not grant any rights under trademark law and all such -rights are reserved. - -Permission is hereby granted, free of charge, to any person obtaining a -copy of the Font Software, to propagate the Font Software, subject to -the below conditions: - -1) Each copy of the Font Software must contain the above copyright -notice and this licence. These can be included either as stand-alone -text files, human-readable headers or in the appropriate machine- -readable metadata fields within text or binary files as long as those -fields can be easily viewed by the user. - -2) The font name complies with the following: -(a) The Original Version must retain its name, unmodified. -(b) Modified Versions which are Substantially Changed must be renamed to -avoid use of the name of the Original Version or similar names entirely. -(c) Modified Versions which are not Substantially Changed must be -renamed to both (i) retain the name of the Original Version and (ii) add -additional naming elements to distinguish the Modified Version from the -Original Version. The name of such Modified Versions must be the name of -the Original Version, with "derivative X" where X represents the name of -the new work, appended to that name. - -3) The name(s) of the Copyright Holder(s) and any contributor to the -Font Software shall not be used to promote, endorse or advertise any -Modified Version, except (i) as required by this licence, (ii) to -acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with -their explicit written permission. - -4) The Font Software, modified or unmodified, in part or in whole, must -be distributed entirely under this licence, and must not be distributed -under any other licence. The requirement for fonts to remain under this -licence does not affect any document created using the Font Software, -except any version of the Font Software extracted from a document -created using the Font Software may only be distributed under this -licence. - -TERMINATION -This licence becomes null and void if any of the above conditions are -not met. - -DISCLAIMER -THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF -COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE -COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL -DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER -DEALINGS IN THE FONT SOFTWARE. diff --git a/docs/.sphinx/fonts/Ubuntu-B.ttf b/docs/.sphinx/fonts/Ubuntu-B.ttf deleted file mode 100644 index b173da2..0000000 Binary files a/docs/.sphinx/fonts/Ubuntu-B.ttf and /dev/null differ diff --git a/docs/.sphinx/fonts/Ubuntu-R.ttf b/docs/.sphinx/fonts/Ubuntu-R.ttf deleted file mode 100644 index d748728..0000000 Binary files a/docs/.sphinx/fonts/Ubuntu-R.ttf and /dev/null differ diff --git a/docs/.sphinx/fonts/Ubuntu-RI.ttf b/docs/.sphinx/fonts/Ubuntu-RI.ttf deleted file mode 100644 index 4f2d2bc..0000000 Binary files a/docs/.sphinx/fonts/Ubuntu-RI.ttf and /dev/null differ diff --git a/docs/.sphinx/fonts/UbuntuMono-B.ttf b/docs/.sphinx/fonts/UbuntuMono-B.ttf deleted file mode 100644 index 7bd6665..0000000 Binary files a/docs/.sphinx/fonts/UbuntuMono-B.ttf and /dev/null differ diff --git a/docs/.sphinx/fonts/UbuntuMono-R.ttf b/docs/.sphinx/fonts/UbuntuMono-R.ttf deleted file mode 100644 index fdd309d..0000000 Binary files a/docs/.sphinx/fonts/UbuntuMono-R.ttf and /dev/null differ diff --git a/docs/.sphinx/fonts/UbuntuMono-RI.ttf b/docs/.sphinx/fonts/UbuntuMono-RI.ttf deleted file mode 100644 index 18f81a2..0000000 Binary files a/docs/.sphinx/fonts/UbuntuMono-RI.ttf and /dev/null differ diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py index 9ee2d0b..cb73a64 100644 --- a/docs/.sphinx/get_vale_conf.py +++ b/docs/.sphinx/get_vale_conf.py @@ -5,7 +5,6 @@ DIR = os.getcwd() - def main(): if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"): print("Vale directory exists") @@ -23,6 +22,22 @@ def main(): file.write(download.text) file.close() + # Update dictionary + if os.path.exists(f"{DIR}/.sphinx/styles/config/dictionaries"): + print("Dictionary directory exists") + else: + os.makedirs(f"{DIR}/.sphinx/styles/config/dictionaries") + url = ( + "https://api.github.com/repos/canonical/praecepta/" + + "contents/styles/config/dictionaries" + ) + r = requests.get(url) + for item in r.json(): + download = requests.get(item["download_url"]) + file = open(".sphinx/styles/config/dictionaries/" + item["name"], "w") + file.write(download.text) + file.close() + if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"): print("Vocab directory exists") else: diff --git a/docs/.sphinx/images/Canonical-logo-4x.png b/docs/.sphinx/images/Canonical-logo-4x.png deleted file mode 100644 index fd75696..0000000 Binary files a/docs/.sphinx/images/Canonical-logo-4x.png and /dev/null differ diff --git a/docs/.sphinx/images/front-page-light.pdf b/docs/.sphinx/images/front-page-light.pdf deleted file mode 100644 index bb68cdf..0000000 Binary files a/docs/.sphinx/images/front-page-light.pdf and /dev/null differ diff --git a/docs/.sphinx/images/normal-page-footer.pdf b/docs/.sphinx/images/normal-page-footer.pdf deleted file mode 100644 index dfd73cb..0000000 Binary files a/docs/.sphinx/images/normal-page-footer.pdf and /dev/null differ diff --git a/docs/.sphinx/latex_elements_template.txt b/docs/.sphinx/latex_elements_template.txt deleted file mode 100644 index 322412c..0000000 --- a/docs/.sphinx/latex_elements_template.txt +++ /dev/null @@ -1,119 +0,0 @@ -{ - 'papersize': 'a4paper', - 'pointsize': '11pt', - 'fncychap': '', - 'preamble': r''' -%\usepackage{charter} -%\usepackage[defaultsans]{lato} -%\usepackage{inconsolata} -\setmainfont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{Ubuntu} -\setmonofont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{UbuntuMono} -\usepackage[most]{tcolorbox} -\tcbuselibrary{breakable} -\usepackage{lastpage} -\usepackage{tabto} -\usepackage{ifthen} -\usepackage{etoolbox} -\usepackage{fancyhdr} -\usepackage{graphicx} -\usepackage{titlesec} -\usepackage{fontspec} -\usepackage{tikz} -\usepackage{changepage} -\usepackage{array} -\usepackage{tabularx} -\definecolor{yellowgreen}{RGB}{154, 205, 50} -\definecolor{title}{RGB}{76, 17, 48} -\definecolor{subtitle}{RGB}{116, 27, 71} -\definecolor{label}{RGB}{119, 41, 100} -\definecolor{copyright}{RGB}{174, 167, 159} -\makeatletter -\def\tcb@finalize@environment{% - \color{.}% hack for xelatex - \tcb@layer@dec% -} -\makeatother -\newenvironment{sphinxclassprompt}{\color{yellowgreen}\setmonofont[Color = 9ACD32, UprightFont = *-R, Extension = .ttf]{UbuntuMono}}{} -\tcbset{enhanced jigsaw, colback=black, fontupper=\color{white}} -\newtcolorbox{termbox}{use color stack, breakable, colupper=white, halign=flush left} -\newenvironment{sphinxclassterminal}{\setmonofont[Color = white, UprightFont = *-R, Extension = .ttf]{UbuntuMono}\sphinxsetup{VerbatimColor={black}}\begin{termbox}}{\end{termbox}} -\newcommand{\dimtorightedge}{% - \dimexpr\paperwidth-1in-\hoffset-\oddsidemargin\relax} -\newcommand{\dimtotop}{% - \dimexpr\height-1in-\voffset-\topmargin-\headheight-\headsep\relax} -\newtoggle{tpage} -\AtBeginEnvironment{titlepage}{\global\toggletrue{tpage}} -\fancypagestyle{plain}{ - \fancyhf{} - \fancyfoot[R]{\thepage\ of \pageref*{LastPage}} - \renewcommand{\headrulewidth}{0pt} - \renewcommand{\footrulewidth}{0pt} -} -\fancypagestyle{normal}{ - \fancyhf{} - \fancyfoot[R]{\thepage\ of \pageref*{LastPage}} - \renewcommand{\headrulewidth}{0pt} - \renewcommand{\footrulewidth}{0pt} -} -\fancypagestyle{titlepage}{% - \fancyhf{} - \fancyfoot[L]{\footnotesize \textcolor{copyright}{© 2024 Canonical Ltd. All rights reserved.}} -} -\newcommand\sphinxbackoftitlepage{\thispagestyle{titlepage}} -\titleformat{\chapter}[block]{\Huge \color{title} \bfseries\filright}{\thechapter .}{1.5ex}{} -\titlespacing{\chapter}{0pt}{0pt}{0pt} -\titleformat{\section}[block]{\huge \bfseries\filright}{\thesection .}{1.5ex}{} -\titlespacing{\section}{0pt}{0pt}{0pt} -\titleformat{\subsection}[block]{\Large \bfseries\filright}{\thesubsection .}{1.5ex}{} -\titlespacing{\subsection}{0pt}{0pt}{0pt} -\setcounter{tocdepth}{1} -\renewcommand\pagenumbering[1]{} -''', - 'sphinxsetup': 'verbatimwithframe=false, pre_border-radius=0pt, verbatimvisiblespace=\\phantom{}, verbatimcontinued=\\phantom{}', - 'extraclassoptions': 'openany,oneside', - 'maketitle': r''' -\begin{titlepage} -\begin{flushleft} - \begin{tikzpicture}[remember picture,overlay] - \node[anchor=south east, inner sep=0] at (current page.south east) { - \includegraphics[width=\paperwidth, height=\paperheight]{front-page-light} - }; - \end{tikzpicture} -\end{flushleft} - -\vspace*{3cm} - -\begin{adjustwidth}{8cm}{0pt} -\begin{flushleft} - \huge \textcolor{black}{\textbf{}{\raggedright{$PROJECT}}} -\end{flushleft} -\end{adjustwidth} - -\vfill - -\begin{adjustwidth}{8cm}{0pt} -\begin{tabularx}{0.5\textwidth}{ l l } - \textcolor{lightgray}{© 2024 Canonical Ltd.} & \hspace{3cm} \\ - \textcolor{lightgray}{All rights reserved.} & \hspace{3cm} \\ - & \hspace{3cm} \\ - & \hspace{3cm} \\ - -\end{tabularx} -\end{adjustwidth} - -\end{titlepage} -\RemoveFromHook{shipout/background} -\AddToHook{shipout/background}{ - \begin{tikzpicture}[remember picture,overlay] - \node[anchor=south west, align=left, inner sep=0] at (current page.south west) { - \includegraphics[width=\paperwidth]{normal-page-footer} - }; - \end{tikzpicture} - \begin{tikzpicture}[remember picture,overlay] - \node[anchor=north east, opacity=0.5, inner sep=35] at (current page.north east) { - \includegraphics[width=4cm]{Canonical-logo-4x} - }; - \end{tikzpicture} - } -''', -} \ No newline at end of file diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json index 8df0cb9..04dc1e1 100644 --- a/docs/.sphinx/pa11y.json +++ b/docs/.sphinx/pa11y.json @@ -6,4 +6,4 @@ }, "reporter": "cli", "standard": "WCAG2AA" -} \ No newline at end of file +} diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt index c1cc388..9ff666c 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/.sphinx/requirements.txt @@ -1,3 +1,4 @@ -canonical-sphinx[full] @ git+https://github.com/canonical/canonical-sphinx@main +canonical-sphinx[full] sphinx-autobuild -sphinxcontrib-svg2pdfconverter[CairoSVG] \ No newline at end of file +sphinxcontrib-svg2pdfconverter[CairoSVG] +sphinx-last-updated-by-git diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml index a82701b..417a541 100644 --- a/docs/.sphinx/spellingcheck.yaml +++ b/docs/.sphinx/spellingcheck.yaml @@ -28,5 +28,3 @@ matrix: - img - a.p-navigation__link - a.contributor - - pyspelling.filters.context: - escapes: '\\bhttps?://[^\\s]+\\b' diff --git a/docs/Makefile b/docs/Makefile index 72fe7c6..ed131dc 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,11 +1,23 @@ -# This Makefile stub allows you to customize starter pack (SP) targets. -# Consider this file as a bridge between your project -# and the starter pack's predefined targets that reside in Makefile.sp. +# Minimal makefile for Sphinx documentation # -# You can add your own, non-SP targets here or override SP targets -# to fit your project's needs. For example, you can define and use targets -# named "install" or "run", but continue to use SP targets like "sp-install" -# or "sp-run" when working on the documentation. +# Add your customisation to `Makefile` instead. + +# 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 = * +ALLFILES = *.rst **/*.rst +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 # Put it first so that "make" without argument is like "make help". help: @@ -27,5 +39,158 @@ help: "* other possible targets: make \n" \ "------------------------------------------------------------- \n" +.PHONY: full-help woke-install spellcheck-install pa11y-install install run html \ + epub serve clean clean-doc spelling spellcheck linkcheck woke \ + allmetrics pa11y pdf-prep-force pdf-prep pdf Makefile.sp vale-install vale + +full-help: $(VENVDIR) + @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m" + @echo "Run 'make help' to see supported targets." + +# If requirements are updated, venv should be rebuilt and timestamped. +$(VENVDIR): + python3 -c "import venv" || \ + (echo "You must install python3-venv before you can build the documentation."; exit 1) + @echo "... setting up virtualenv" + python3 -m venv $(VENVDIR) + . $(VENV); pip install $(PIPOPTS) --require-virtualenv \ + --upgrade -r $(SPHINXDIR)/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 + @touch $(VENVDIR) + +spellcheck-install: + @type aspell >/dev/null 2>&1 || \ + { \ + echo "Installing system-wide \"aspell\" packages..."; \ + confirm_sudo=$(CONFIRM_SUDO); \ + if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \ + read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \ + fi; \ + if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \ + sudo apt-get install aspell aspell-en; \ + else \ + echo "Installation cancelled."; \ + fi \ + } + +pa11y-install: + @type $(PA11Y) >/dev/null 2>&1 || { \ + echo "Installing \"pa11y\" from npm... \n"; \ + mkdir -p $(SPHINXDIR)/node_modules/ ; \ + npm install --prefix $(SPHINXDIR) pa11y; \ + } + +install: $(VENVDIR) + +run: install + . $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + +# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. +html: install + . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +epub: install + . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +serve: html + cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000 + +clean: clean-doc + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + rm -rf $(VENVDIR) + rm -rf $(SPHINXDIR)/node_modules/ + rm -rf $(SPHINXDIR)/styles + rm -rf $(VALE_CONFIG) + +clean-doc: + git clean -fx "$(BUILDDIR)" + rm -rf $(SPHINXDIR)/.doctrees + +spellcheck: spellcheck-install + . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) + +spelling: html spellcheck + +linkcheck: install + . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; } + exit 0 + +pa11y: pa11y-install html + find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) + +vale-install: install + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale + @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py + @printf '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter + @printf '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter + @printf '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \; + +woke: vale-install + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @printf "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command\n" + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET) || true + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + +vale: vale-install + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n" + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) || true + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + +vale-spelling: vale-install + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n" + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) || true + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + +pdf-prep: install + @for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \ + grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \ + (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \ + echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \ + "Please be aware these packages will be installed to your system") && exit 1 ; done + +pdf-prep-force: + apt-get update + apt-get upgrade -y + apt-get install --no-install-recommends -y $(REQPDFPACKS) \ + +pdf: pdf-prep + @. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + @rm ./$(BUILDDIR)/latex/front-page-light.pdf || true + @rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true + @find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} + + @rm -r $(BUILDDIR)/latex + @echo "\nOutput can be found in ./$(BUILDDIR)\n" + +allmetrics: html + @echo "Recording documentation metrics..." + @echo "Checking for existence of vale..." + . $(VENV) + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale + @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \; + @eval '$(METRICSDIR)/source_metrics.sh $(PWD)' + @eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)' + +# Generate formatted docx files using Pandoc +html-docx: install + . $(VENV); DEFAULT="False" $(SPHINXBUILD) -t docx -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + . $(VENV); pip install beautifulsoup4 lxml python-docx + . $(VENV); sudo apt-get -y install pandoc + . $(VENV); python3 ./scripts/minimal-html.py + . $(VENV); python3 ./scripts/pandoc.py + . $(VENV); python3 ./scripts/format-docx.py + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: - $(MAKE) -f Makefile.sp sp-$@ + . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/Makefile.sp b/docs/Makefile.sp deleted file mode 100644 index e3abe6a..0000000 --- a/docs/Makefile.sp +++ /dev/null @@ -1,180 +0,0 @@ -# Minimal makefile for Sphinx documentation -# -# `Makefile.sp` is from the Sphinx starter pack and should not be -# modified. -# Add your customisation to `Makefile` instead. - -# 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 = * -ALLFILES = *.rst **/*.rst -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 - -.PHONY: sp-full-help sp-woke-install sp-spellcheck-install sp-pa11y-install sp-install sp-run sp-html \ - sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \ - sp-allmetrics sp-pa11y sp-pdf-prep-force sp-pdf-prep sp-pdf Makefile.sp sp-vale sp-bash - -sp-full-help: $(VENVDIR) - @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m" - @echo "Run 'make help' to see supported targets." - -# If requirements are updated, venv should be rebuilt and timestamped. -$(VENVDIR): - python3 -c "import venv" || \ - (echo "You must install python3-venv before you can build the documentation."; exit 1) - @echo "... setting up virtualenv" - python3 -m venv $(VENVDIR) - . $(VENV); pip install $(PIPOPTS) --require-virtualenv \ - --upgrade -r $(SPHINXDIR)/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 - @touch $(VENVDIR) - -sp-woke-install: - @type woke >/dev/null 2>&1 || \ - { \ - echo "Installing system-wide \"woke\" snap..."; \ - confirm_sudo=$(CONFIRM_SUDO); \ - if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \ - read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \ - fi; \ - if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \ - sudo snap install woke; \ - else \ - echo "Installation cancelled."; \ - fi \ - } - -sp-spellcheck-install: - @type aspell >/dev/null 2>&1 || \ - { \ - echo "Installing system-wide \"aspell\" packages..."; \ - confirm_sudo=$(CONFIRM_SUDO); \ - if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \ - read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \ - fi; \ - if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \ - sudo apt-get install aspell aspell-en; \ - else \ - echo "Installation cancelled."; \ - fi \ - } - -sp-pa11y-install: - @type $(PA11Y) >/dev/null 2>&1 || { \ - echo "Installing \"pa11y\" from npm... \n"; \ - mkdir -p $(SPHINXDIR)/node_modules/ ; \ - npm install --prefix $(SPHINXDIR) pa11y; \ - } - -sp-install: $(VENVDIR) - -sp-run: sp-install - . $(VENV); DEFAULT="True" $(VENVDIR)/bin/sphinx-autobuild -t default -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) - -# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. -sp-html: sp-install - . $(VENV); DEFAULT="True" $(SPHINXBUILD) -W --keep-going -t default -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) - -sp-epub: sp-install - . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) - -sp-serve: sp-html - cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000 - -sp-clean: sp-clean-doc - @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" - rm -rf $(VENVDIR) - rm -rf $(SPHINXDIR)/node_modules/ - rm -rf $(SPHINXDIR)/styles - rm -rf $(SPHINXDIR)/vale.ini - -sp-clean-doc: - git clean -fx "$(BUILDDIR)" - rm -rf $(SPHINXDIR)/.doctrees - -sp-spellcheck: sp-spellcheck-install - . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) - -sp-spelling: sp-html sp-spellcheck - -sp-linkcheck: sp-install - . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; } - exit 0 - -sp-woke: sp-woke-install - woke $(ALLFILES) --exit-1-on-failure \ - -c https://raw.githubusercontent.com/canonical/Inclusive-naming/main/config.yml - -sp-pa11y: sp-pa11y-install sp-html - find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) - -sp-vale: sp-install - @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale - @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py - @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; - @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt - @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt - @echo "" - @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" - @echo "" - @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET) || true - @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt - -sp-pdf-prep: sp-install - @for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \ - grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \ - (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \ - echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \ - "Please be aware these packages will be installed to your system") && exit 1 ; done - -sp-pdf-prep-force: - apt-get update - apt-get upgrade -y - apt-get install --no-install-recommends -y $(REQPDFPACKS) \ - -sp-pdf: sp-pdf-prep - @. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) - @rm ./$(BUILDDIR)/latex/front-page-light.pdf || true - @rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true - @find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} + - @rm -r $(BUILDDIR)/latex - @echo "\nOutput can be found in ./$(BUILDDIR)\n" - -sp-allmetrics: sp-html - @echo "Recording documentation metrics..." - @echo "Checking for existence of vale..." - . $(VENV) - @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale - @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py - @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; - @eval '$(METRICSDIR)/source_metrics.sh $(PWD)' - @eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)' - - -# Generate formatted docx files using Pandoc -sp-html-docx: sp-install - . $(VENV); DEFAULT="False" $(SPHINXBUILD) -t docx -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) - . $(VENV); pip install beautifulsoup4 lxml python-docx - . $(VENV); sudo apt-get -y install pandoc - . $(VENV); python3 ./scripts/minimal-html.py - . $(VENV); python3 ./scripts/pandoc.py - . $(VENV); python3 ./scripts/format-docx.py - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile.sp - . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index aac9423..ff9bfa8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -70,7 +70,7 @@ # NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph # and is used by social media platforms; see https://ogp.me/ -ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/" +ogp_site_url = "https://canonical-kernel-docs.readthedocs-hosted.com/" # Preview name of the documentation website @@ -84,8 +84,7 @@ # # TODO: To customise the preview image, update as needed. -ogp_image = \ - "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg" +ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg" # Product favicon; shown in bookmarks, browser tabs, etc. @@ -107,7 +106,7 @@ # TODO: If there's no such website, # remove the {{ product_page }} link from the page header template # (usually .sphinx/_templates/header.html; also, see README.rst). - "product_page": "documentation.ubuntu.com", + "product_page": "kernel.ubuntu.com", # Product tag image; the orange part of your logo, shown in the page header # # TODO: To add a tag image, uncomment and update as needed. @@ -122,8 +121,7 @@ # Your Mattermost channel URL # # TODO: Change to your Mattermost channel URL or leave empty. - "mattermost": - "", + "mattermost": "https://chat.canonical.com/canonical/channels/kernel", # Your Matrix channel URL # # TODO: Change to your Matrix channel URL or leave empty. @@ -138,15 +136,21 @@ # Docs branch in the repo; used in links for viewing the source files # # TODO: To customise the branch, uncomment and update as needed. - # 'github_version': 'main', + 'repo_default_branch': 'main', # Docs location in the repo; used in links for viewing the source files # - # TODO: To customise the directory, uncomment and update as needed. - "github_folder": "/docs/", + + # TODO: To customise the directory, uncomment and update as needed. + "repo_folder": "/docs/", # TODO: To enable or disable the Previous / Next buttons at the bottom of pages # Valid options: none, prev, next, both - "sequential_nav": "both" + # "sequential_nav": "both", + # TODO: To enable listing contributors on individual pages, set to True + "display_contributors": False, + + # Required for feedback button + 'github_issues': 'enabled', } # Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897 @@ -178,6 +182,9 @@ redirects = { "reference/patch_acceptance_criteria/index.html": "../patch-acceptance-criteria/", + "how-to/develop-customize/": "how-to/develop-customise/", + "how-to/develop-customize/build-kernel/": "how-to/develop-customise/build-kernel/", + "how-to/develop-customize/build-kernel-snap/": "how-to/develop-customise/build-kernel-snap/", } @@ -192,7 +199,7 @@ linkcheck_ignore = [ "http://127.0.0.1:8000", "https://github.com/canonical/ACME/*" -] + ] # A regex list of URLs where anchors are ignored by 'make linkcheck' @@ -203,6 +210,9 @@ r"https://snapcraft.io/docs/", ] +# give linkcheck multiple tries on failure +# linkcheck_timeout = 30 +linkcheck_retries = 3 ######################## # Configuration extras # @@ -216,6 +226,7 @@ # myst_enable_extensions = set() + # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html @@ -239,7 +250,6 @@ "sphinxcontrib.cairosvgconverter", ] - # Excludes files or directories from processing exclude_patterns = [ @@ -292,6 +302,10 @@ :class: align-center .. role:: h2 :class: hclass2 +.. role:: woke-ignore + :class: woke-ignore +.. role:: vale-ignore + :class: vale-ignore """ # Workaround for https://github.com/canonical/canonical-sphinx/issues/34 @@ -299,31 +313,6 @@ if "discourse_prefix" not in html_context and "discourse" in html_context: html_context["discourse_prefix"] = html_context["discourse"] + "/t/" -##################### -# PDF configuration # -##################### - -latex_additional_files = [ - "./.sphinx/fonts/Ubuntu-B.ttf", - "./.sphinx/fonts/Ubuntu-R.ttf", - "./.sphinx/fonts/Ubuntu-RI.ttf", - "./.sphinx/fonts/UbuntuMono-R.ttf", - "./.sphinx/fonts/UbuntuMono-RI.ttf", - "./.sphinx/fonts/UbuntuMono-B.ttf", - "./.sphinx/images/Canonical-logo-4x.png", - "./.sphinx/images/front-page-light.pdf", - "./.sphinx/images/normal-page-footer.pdf", -] - -latex_engine = "xelatex" -latex_show_pagerefs = True -latex_show_urls = "footnote" - -with open(".sphinx/latex_elements_template.txt", "rt") as file: - latex_config = file.read() - -latex_elements = ast.literal_eval(latex_config.replace("$PROJECT", project)) - ###################### # DOCX configuration # ###################### diff --git a/docs/how-to/develop-customize/build-kernel-snap.md b/docs/how-to/develop-customise/build-kernel-snap.md similarity index 100% rename from docs/how-to/develop-customize/build-kernel-snap.md rename to docs/how-to/develop-customise/build-kernel-snap.md diff --git a/docs/how-to/develop-customize/build-kernel.md b/docs/how-to/develop-customise/build-kernel.md similarity index 98% rename from docs/how-to/develop-customize/build-kernel.md rename to docs/how-to/develop-customise/build-kernel.md index 898fe71..067f919 100644 --- a/docs/how-to/develop-customize/build-kernel.md +++ b/docs/how-to/develop-customise/build-kernel.md @@ -33,7 +33,7 @@ Otherwise, skip ahead to {ref}`how-to-build-kernel-obtain-source`. To build an Ubuntu kernel, you will need to enable the necessary source repositories in the `sources.list` or `ubuntu.sources` file. -See {file}`` for details. +See {doc}`/how-to/source-code/enable-source-repositories` for details. (how-to-build-kernel-install-packages)= ### Install required packages diff --git a/docs/how-to/develop-customize/index.md b/docs/how-to/develop-customise/index.md similarity index 100% rename from docs/how-to/develop-customize/index.md rename to docs/how-to/develop-customise/index.md diff --git a/docs/how-to/index.md b/docs/how-to/index.md index ba070ef..2d39257 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -9,7 +9,7 @@ kernel packages and components. :hidden: Source code access and management -Development and customization +Development and customization Test kernels in -proposed Contribute to kernel docs ``` @@ -27,8 +27,8 @@ tree to build custom kernel modules, and more. The steps to build a kernel is similar but may have slightly difference configuration requirements on different platforms and/or architectures. -- [Build an Ubuntu Linux kernel](/how-to/develop-customize/build-kernel) -- [Build an Ubuntu Linux kernel snap](/how-to/develop-customize/build-kernel-snap) +- [Build an Ubuntu Linux kernel](/how-to/develop-customise/build-kernel) +- [Build an Ubuntu Linux kernel snap](/how-to/develop-customise/build-kernel-snap) ## Testing and verification