Update extension based SP with content from main (#289)

.gitignore

@@ -1 +1,2 @@
 testdir
+sp-docs/_build

README.rst

@@ -1 +1,48 @@
-See the documentation at https://canonical-starter-pack.readthedocs-hosted.com/use-canonical-sphinx-extension/
+Canonical's Sphinx Starter Pack
+===============================
+
+*A pre-configured repository to build and publish documentation with Sphinx.*
+
+Description
+-----------
+
+The Documentation starter pack includes:
+
+* A bundled Sphinx_ theme, configuration, and extensions
+* Support for both reStructuredText (reST) and MyST Markdown
+* Build checks for links, spelling, and inclusive language
+* Customisation support layered over a core configuration
+
+See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/use-canonical-sphinx-extension/
+
+Structure
+---------
+
+This section outlines the structure of this repository, and some key files.
+
+init.sh
+*******
+
+This script is an entrypoint intended to simplify adoption of this starter pack.
+Download and run this file it to install the starter pack in an arbitrary directory of the repo.
+
+sp-files
+********
+
+This directory contains the files required for the functionality of the starter pack.
+If you don't want to run ``init.sh`` for some reason, use these files.
+
+sp-docs
+*******
+
+This directory contains the documentation for the starter pack itself.
+To view it in your browser, change to this directory and type `make run`.
+
+sp-tests
+********
+
+This directory contains files used to test the functionality of the starter pack project.
+
+.. LINKS
+
+.. _`Sphinx`: https://www.sphinx-doc.org/

init.sh

@@ -50,7 +50,7 @@ temp_directory="temp-starter-pack-$(date +%Y%m%d%H%M%S)"
 
 # Clone the starter pack repository into the temporary directory and de-git it
 echo "Cloning the starter pack repository..."
-git clone --depth 1 -b use-canonical-sphinx-extension --single-branch https://github.com/canonical/starter-pack "$temp_directory"
+git clone --depth 1 -b extension-main-combined --single-branch https://github.com/canonical/starter-pack "$temp_directory"
 rm -rf "$temp_directory/.git"
 
 # Update workflow and documentation files based on the installation directory
@@ -61,6 +61,7 @@ sed -i "s|configuration:\s*sp-docs/conf\.py|configuration: $install_directory/co
 sed -i "s|requirements:\s*sp-docs/\.sphinx/requirements\.txt|requirements: $install_directory/.sphinx/requirements.txt|g" "$temp_directory/sp-files/.readthedocs.yaml"
 echo "Updating contribution guide..."
 sed -i "s|DOCDIR|$install_directory|g" "$temp_directory/sp-files/contributing.rst"
+[ "$install_directory" != "." ] && sed -i "s/Makefile.sp/$install_directory\/Makefile.sp/" "$temp_directory/sp-files/.github/workflows/sphinx-python-dependency-build-checks.yml"
 
 # Update the GitHub folder path in the configuration file
 echo "Updating conf.py configuration..."

sp-docs/.custom_wordlist.txt

@@ -1 +1,2 @@
-WCAG
+# Leave a blank line at the end of this file to support concatenation 
+WCAG

sp-docs/docs/build.rst

@@ -65,3 +65,47 @@ When you change a documentation file and save it, the documentation will be auto
    If you save other files later, you might miss these messages.
 
    Therefore, you should always :ref:`build-clean` before finalising your changes.
+
+Build a PDF
+-----------
+
+Build a PDF locally with the following command:
+
+.. code-block:: none
+
+    make pdf
+
+PDF generation requires specific software packages. If these files are not found, a prompt will be presented and the generation will stop.
+
+Required software packages include:
+
+* dvipng
+* fonts-freefont-otf
+* latexmk
+* plantuml
+* tex-gyre
+* texlive-font-utils
+* texlive-fonts-recommended
+* texlive-lang-cjk
+* texlive-latex-extra
+* texlive-latex-recommended
+* texlive-xetex
+* xindy
+
+On Linux, required packages can be installed with:
+
+.. code-block:: none
+
+    make pdf-prep-force
+
+.. note::
+
+    When generating a PDF, the index page is considered a 'foreword' and will not be labelled with a chapter.
+
+.. important::
+
+    When generating a PDF, it is important to not use additional headings before a ``toctree``. Documents referenced by the
+    ``toctree`` will be nested under any provided headings.
+
+    A ``rubric`` directive can be combined with the ``h2`` class to provide a heading-styled rubric in the HTML output. See the default ``index.rst`` for an example.
+    Rubric-based headings aren't included as entries in the table of contents or the navigation sidebar.

sp-docs/docs/customise.rst

@@ -83,21 +83,21 @@ They are pre-configured as needed, but you can customise their configuration in
 
 The following extensions are always included:
 
-- :literalref:`sphinx-design <https://sphinx-design.readthedocs.io/en/latest/>`
-- :literalref:`sphinx_copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`
+- :literalref:`myst_parser <https://myst-parser.readthedocs.io/en/latest/>`
 - :literalref:`sphinxcontrib.jquery <https://github.com/sphinx-contrib/jquery/>`
 
-The following extensions are included unless they are disabled when loading the extension:
+The following extensions are included with the ``[full]`` optional install of canonical-sphinx:
 
+- :literalref:`sphinx-design <https://sphinx-design.readthedocs.io/en/latest/>`
+- :literalref:`sphinx_copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`
 - :literalref:`sphinx_tabs.tabs <https://sphinx-tabs.readthedocs.io/en/latest/>`
 - :literalref:`sphinx_reredirects <https://documatt.gitlab.io/sphinx-reredirects/>`
 - :literalref:`sphinxext.opengraph <https://sphinxext-opengraph.readthedocs.io/en/latest/>`
 - :literalref:`canonical-sphinx-extensions <https://github.com/canonical/canonical-sphinx-extensions>` (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``)
-- :literalref:`myst_parser <https://myst-parser.readthedocs.io/en/latest/>`
 - :literalref:`notfound.extension <https://sphinx-notfound-page.readthedocs.io/en/latest/>`
 
-You can add further extensions in the ``extensions`` variable in :file:`conf.py`.
-If the extensions need specific Python packages, add those to the :file:`requirements.py` file.
+None of the extensions referenced in this section need to be added to the ``extensions`` variable in :file:`conf.py`.
+If the extensions need specific Python packages, add those to the :file:`requirements.txt` file.
 
 Add page-specific configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sp-files/.github/workflows/sphinx-python-dependency-build-checks.yml

@@ -0,0 +1,48 @@
+# 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
+        run: |
+          set -ex
+          make -f Makefile.sp \
+            sp-install \
+            PIPOPTS="--no-binary :all:" \
+            || ( cat .sphinx/venv/pip_install.log && exit 1 )

sp-files/.sphinx/.wordlist.txt

@@ -1,7 +1,3 @@
-# This wordlist is from the Sphinx starter pack and should not be
-# modified. Add any custom terms to .custom_wordlist.txt instead.
-
-
 ACME
 ACME's
 addons
@@ -13,6 +9,7 @@ Charmhub
 CLI
 DCO
 Diátaxis
+Dqlite
 dropdown
 EBS
 EKS

sp-files/.sphinx/_static/css/pdf.css

@@ -0,0 +1,15 @@
+/* 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;
+}

sp-files/.sphinx/fonts/LICENCE.txt

@@ -0,0 +1,96 @@
+-------------------------------
+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.