Merge pull request #240 from ru-fu/build-improvements

Build improvements

Makefile

@@ -1,7 +1,7 @@
 # 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.
-# 
+#
 # 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"
@@ -18,6 +18,7 @@ help:
         "* clean full environment:                    make clean \n" \
         "* check links:                               make linkcheck \n" \
         "* check spelling:                            make spelling \n" \
+        "* check spelling (without building again):   make spellcheck \n" \
         "* check inclusive language:                  make woke \n" \
         "* check accessibility:                       make pa11y \n" \
         "* check style guide compliance:              make vale \n" \

Makefile.sp

@@ -7,17 +7,19 @@
 # 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
+SPHINXOPTS    ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
 SPHINXBUILD   ?= 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
+ADDPREREQS    ?=
 
 .PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \
-        sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-linkcheck sp-woke \
+        sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
         sp-pa11y Makefile.sp sp-vale
 
 sp-full-help: $(VENVDIR)
@@ -28,9 +30,13 @@ sp-full-help: $(VENVDIR)
 # Shouldn't assume that venv is available on Ubuntu by default; discussion here:
 # https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847
 $(SPHINXDIR)/requirements.txt:
-	python3 $(SPHINXDIR)/build_requirements.py
-	python3 -c "import venv" || \
+	@python3 -c "import venv" || \
         (echo "You must install python3-venv before you can build the documentation."; exit 1)
+	python3 -m venv $(VENVDIR)
+	@if [ ! -z "$(ADDPREREQS)" ]; then \
+          . $(VENV); pip install --require-virtualenv $(ADDPREREQS); \
+        fi
+	. $(VENV); python3 $(SPHINXDIR)/build_requirements.py
 
 # If requirements are updated, venv should be rebuilt and timestamped.
 $(VENVDIR): $(SPHINXDIR)/requirements.txt
@@ -68,7 +74,7 @@ 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 8000
+	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)"
@@ -82,14 +88,17 @@ sp-clean-doc:
 	git clean -fx "$(BUILDDIR)"
 	rm -rf $(SPHINXDIR)/.doctrees
 
-sp-spelling: sp-html
+sp-spellcheck:
 	. $(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)
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
+	exit 0
 
 sp-woke: sp-woke-install
-	woke *.rst **/*.rst --exit-1-on-failure \
+	woke $(ALLFILES) --exit-1-on-failure \
 	    -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
 
 sp-pa11y: sp-pa11y-install sp-html

doc-cheat-sheet-myst.md

@@ -19,7 +19,9 @@ myst:
 This file contains the syntax for commonly used Markdown and MyST markup.
 Open it in your text editor to quickly copy and paste the markup you need.
 
-Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions.
+See the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) for detailed information and conventions.
+
+Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions.
 
 ## H2 heading
 
@@ -61,13 +63,11 @@ code:
 ## Links
 
 - [Canonical website](https://canonical.com/)
-- https:/<span></span>/canonical.com/
 - {ref}`a_section_target_myst`
 - {ref}`Link text <a_section_target_myst>`
 - {doc}`index`
 - {doc}`Link text <index>`
 
-
 ## Navigation
 
 Use the following syntax::
@@ -83,7 +83,7 @@ Use the following syntax::
 
 1. Step 1
    - Item 1
-     * Sub-item
+      * Sub-item
    - Item 2
      1. Sub-step 1
      1. Sub-step 2
@@ -186,7 +186,7 @@ Keys can be defined at the top of a file, or in a `myst_substitutions` option in
 
 ### File inclusion
 
-```{include} index.rst
+```{include} index.md
    :start-after: include_start
    :end-before: include_end
 ```

readme.rst

@@ -87,6 +87,8 @@ pack* and *Work with your documentation* post-enablement.
     + `Activate/deactivate feedback button`_
     + `Configure included extensions`_
     + `Add custom configuration`_
+    + `Add Python packages`_
+    + `Add page-specific configuration`_
 
   * `Change log`_
 
@@ -281,6 +283,7 @@ The following extensions will automatically be included based on the configurati
 - |notfound.extension|_
 
 You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``.
+If the extensions need specific Python packages, add those to the ``custom_required_modules`` variable.
 
 Add custom configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -294,6 +297,29 @@ The following links can help you with additional configuration:
 - `Sphinx extensions`_
 - `Furo documentation`_ (Furo is the Sphinx theme we use as our base.)
 
+Add Python packages
+^^^^^^^^^^^^^^^^^^^
+
+If you need additional Python packages for any custom processing you do in your documentation, add them to the ``custom_required_modules`` variable in ``custom_conf.py``.
+
+If you use these packages inside of ``custom_conf.py``, you will encounter a circular dependency (see issue `#197`_).
+To work around this problem, add a step that installs the packages to the ``.readthedocs.yaml`` file:
+
+.. code-block:: yaml
+
+  ...
+  jobs:
+    pre_install:
+      - pip install <packages>
+      - python3 .sphinx/build_requirements.py
+      ...
+
+In addition, override the ``ADDPREREQS`` variable in the Makefile with the names of the packages.
+For example::
+
+  make html ADDPREREQS='<packages>'
+
+
 Add page-specific configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -491,7 +517,7 @@ To run against all files with a specific extension within a folder:
     make vale TARGET=*.md
 
 .. note::
-    
+
     Wildcards can be used to run against all files matching a string, or an extension. The example above will match against all :code:`.md`
     files, and :code:`TARGET=doc*` will match both :code:`doc_1.md` and :code:`doc_2.md`.
 
@@ -652,4 +678,5 @@ Other resources
 .. |notfound.extension| replace:: ``notfound.extension``
 .. _notfound.extension: https://sphinx-notfound-page.readthedocs.io/en/latest/
 
-.. _woke documentation: https://docs.getwoke.tech/ignore
+.. _woke documentation: https://docs.getwoke.tech/ignore
+.. _#197: https://github.com/canonical/sphinx-docs-starter-pack/issues/197