diff --git a/Makefile b/Makefile index cd4bdb8a..a861ba84 100644 --- a/Makefile +++ b/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" \ diff --git a/Makefile.sp b/Makefile.sp index 8ed9c1dd..61c42cf8 100644 --- a/Makefile.sp +++ b/Makefile.sp @@ -7,7 +7,7 @@ # 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 @@ -15,9 +15,11 @@ 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 diff --git a/doc-cheat-sheet-myst.md b/doc-cheat-sheet-myst.md index 39ca355e..6257c9db 100644 --- a/doc-cheat-sheet-myst.md +++ b/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://canonical.com/ - {ref}`a_section_target_myst` - {ref}`Link text ` - {doc}`index` - {doc}`Link text ` - ## 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 ``` diff --git a/readme.rst b/readme.rst index 6d339b5e..ad327e18 100644 --- a/readme.rst +++ b/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 + - 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='' + + 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 \ No newline at end of file +.. _woke documentation: https://docs.getwoke.tech/ignore +.. _#197: https://github.com/canonical/sphinx-docs-starter-pack/issues/197