diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..d2877dc --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,49 @@ +name: Build documentation, check links, spelling, grammar, and style +on: + push: + branches: + - main + paths: + - 'docs/**' + # Build pull requests + pull_request: + paths: + - 'docs/**' + - 'styles/**' + - '.github/workflows/rtd-pr-preview.yml' + - '.github/workflows/test.yml' + - '.readthedocs.yaml' + - '.vale.ini' + - 'requirements-docs.txt' + +jobs: + docs: + name: Documentation + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.12'] + steps: + - uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + cache-dependency-path: 'requirements-docs.txt' + + - name: Create Python virtual environment + run: pip install virtualenv + + - name: pip install requirements + run: pip install -r requirements-docs.txt + + - name: Check for broken links + run: make linkcheckbroken + + - name: Build HTML documentation + run: make html + + - name: Run vale + run: make vale VALEOPTS="--minAlertLevel='warning'" diff --git a/Makefile b/Makefile index a163180..62eb8f5 100644 --- a/Makefile +++ b/Makefile @@ -17,6 +17,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . VALEFILES := $(shell find $(DOCS_DIR) -type f -name "*.md" -print) +VALEOPTS ?= # Add the following 'help' target to your Makefile # And add help text after each target name starting with '\#\#' @@ -174,7 +175,7 @@ linkcheckbroken: bin/python ## Run linkcheck and show only broken links .PHONY: vale vale: bin/python ## Run Vale style, grammar, and spell checks bin/vale sync - bin/vale --no-wrap $(VALEFILES) + bin/vale --no-wrap $(VALEOPTS) $(VALEFILES) @echo @echo "Vale is finished; look for any errors in the above output." diff --git a/docs/conf.py b/docs/conf.py index d416e11..2323205 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -88,6 +88,7 @@ r"http://0.0.0.0", r"http://127.0.0.1", r"http://localhost", + r"http://someurl", r"http://yoursite", # Ignore file downloads r"^/_static/", @@ -105,6 +106,7 @@ r"https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects". r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects". r"https://stackoverflow.com", # volto and documentation # TODO retest with latest Sphinx. + r"https://.*unsplash.com/", # plone-sphinx-theme r"https://web.archive.org/", # volto r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube ] diff --git a/docs/glossary.md b/docs/glossary.md index e23c0f9..f0ba228 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -58,4 +58,11 @@ Open Graph The [Open Graph protocol](https://ogp.me/) enables any web page to become a rich object in a social graph. For instance, this is used on Facebook to allow any web page to have the same functionality as any other object on Facebook. +Make +make +GNU make + [GNU Make](https://www.gnu.org/software/make/) is a tool which controls the generation of executables and other non-source files of a program from the program's source files. + + Make gets its knowledge of how to build your program from a file called the _makefile_, which lists each of the non-source files and how to compute it from other files. + When you write a program, you should write a makefile for it, so that it is possible to use Make to build and install the program. ``` diff --git a/docs/guides/contribute.md b/docs/guides/contribute.md index 4b59448..a3091fa 100644 --- a/docs/guides/contribute.md +++ b/docs/guides/contribute.md @@ -15,7 +15,7 @@ It also covers the essential commands for building and previewing ## Prerequisites - A supported version of Python, as specified on this documentation's {doc}`home page <../index>` -- GNU Make +- {term}`GNU Make` ## Install Plone Sphinx Theme @@ -54,7 +54,7 @@ See {ref}`update-kitchen-sink-demonstration` for details. ### Update Kitchen Sink demonstration -From time to time, the demonstration files for [Sphinx Themes Gallery](https://sphinx-themes.org/) will be updated. +From time to time, the demonstration files for [Sphinx Themes Gallery](https://sphinx-themes.org/) need to be updated. Plone Sphinx Theme uses these files as a demonstration for its styles. To copy these updated files to Plone Sphinx Theme, run the following command. @@ -76,7 +76,7 @@ This section describes how you can change this theme. ### Add or edit a template Templates are pages of Jinja2 code into which components can be inserted. -Plone Sphinx Theme uses a template, {file}`404.html` to display an HTTP "404 Not Found" response page to visitors when they request a page that does not exist. +Plone Sphinx Theme uses a template, {file}`404.html` to display an HTTP "404 Not Found" response page to visitors when they request a page that doesn't exist. In Plone Sphinx Theme, templates are located in the directory {file}`src/plone_sphinx_theme/theme/plone-sphinx-theme`. diff --git a/docs/guides/contributing-policies.md b/docs/guides/contributing-policies.md index 23ac226..23c3ac7 100644 --- a/docs/guides/contributing-policies.md +++ b/docs/guides/contributing-policies.md @@ -23,11 +23,11 @@ To develop your own theme based on Plone Sphinx Theme, see {doc}`develop`. ## Grant permission to publish -Before you contribute, you must give permission to publish your contribution according to the license we use. +Before you contribute, you must give permission to publish your contribution according to the license that Plone uses. You may give that permission by signing the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). -It is a one-time only process. +It's a one-time only process. -The Plone Sphinx Theme Documentation is licensed under the [GNU General Public License, version 2 (GPLv2)](https://github.com/plone/plone-sphinx-theme/blob/main/LICENSE.md). +The Plone Sphinx Theme Documentation is licensed under the [GNU General Public License, version 2 (GPLv2)](https://github.com/plone/plone-sphinx-theme/blob/main/LICENSE). A copy of the license is included in the root of this repository. A volunteer member of the Plone Foundation will review your signed agreement. diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 8e6541b..58e9623 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -33,25 +33,25 @@ These extensions are built in and can be activated by respective entries in the - [`myst_parser`](https://myst-parser.readthedocs.io/en/latest/) parses MyST, a rich and extensible flavour of Markdown for authoring documentation. - [`sphinx-design`](https://sphinx-design.readthedocs.io/en/latest/), with a configuration name of `sphinx_design`, adds grids, cards, icons, badges, buttons, tabs, and dropdowns. - [`sphinx-examples`](https://ebp-sphinx-examples.readthedocs.io/en/latest/) adds "example snippets" that allow you to show off source Markdown and the result of rendering it in Sphinx. -- [`sphinx-notfound-page`](https://sphinx-notfound-page.readthedocs.io/en/latest/index.html), with a configuration name of `notfound.extension`, creates a custom 404 page and helps generate proper static resource links to render the page properly. +- [`sphinx-notfound-page`](https://sphinx-notfound-page.readthedocs.io/en/latest/index.html), with a configuration name of `notfound.extension`, creates a custom 404 page and helps generate proper static resource links to render the page. - [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) pulls in documentation from Python docstrings to generate reStructuredText which in turn gets parsed by Sphinx and rendered to the output format. - It is used by {doc}`plone:plone.api/index`. + It's used by {doc}`plone:plone.api/index`. - [`sphinx.ext.autosummary`](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html) generates function/method/attribute summary lists. - It is used by {doc}`plone:plone.api/index`. + It's used by {doc}`plone:plone.api/index`. - [`sphinx.ext.graphviz`](https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html) allows you to embed [Graphviz](https://graphviz.org/download/) graphs in your documents. - [`sphinx.ext.ifconfig`](https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html) includes content based on configuration. - [`sphinx.ext.intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) provides linking between separate projects that use Sphinx for documentation. - [`sphinx.ext.todo`](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html) adds support for todo items. - [`sphinx.ext.viewcode`](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html) generates pages of source code modules and links between the source and the description. - It is used by {doc}`plone:plone.api/index`. + It's used by {doc}`plone:plone.api/index`. - [`sphinx_copybutton`](https://sphinx-copybutton.readthedocs.io/en/latest/index.html) adds a little "copy" button to the right of code blocks. - [`sphinx_reredirects`](https://documatt.com/sphinx-reredirects/) handles redirects for moved pages. - [`sphinx_sitemap`](https://pypi.org/project/sphinx-sitemap/) generates multiversion and multilanguage [sitemaps.org](https://www.sitemaps.org/protocol.html) compliant sitemaps. - [`sphinxcontrib.httpdomain`](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/) provides a Sphinx domain for describing HTTP APIs. - It is used by Plone's {doc}`plone:plone.restapi/docs/source/index`. + It's used by Plone's {doc}`plone:plone.restapi/docs/source/index`. - [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example. Supported tools include [`curl`](https://curl.se/), [`wget`](https://www.gnu.org/software/wget/), [`httpie`](https://httpie.io/), and [`python-requests`](https://requests.readthedocs.io/en/latest/). - It is used by Plone's {doc}`plone:plone.restapi/docs/source/index`. + It's used by Plone's {doc}`plone:plone.restapi/docs/source/index`. % - [`sphinxcontrib.mermaid`](https://pypi.org/project/sphinxcontrib-mermaid/) allows you to embed [Mermaid](https://mermaid.js.org/) graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts. - [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard. - [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/). diff --git a/docs/reference/file-system-structure.md b/docs/reference/file-system-structure.md index 2f0ed16..4220d2e 100644 --- a/docs/reference/file-system-structure.md +++ b/docs/reference/file-system-structure.md @@ -56,10 +56,10 @@ Plone Sphinx Theme's file structure follows [that of Sphinx Theme Builder](https ## Autogenerated directories The following directories will be autogenerated when the theme's assets are compiled. -They are included in the project's {file}`.gitignore` file. +They're included in the project's {file}`.gitignore` file. `.nodeenv` -: The Node.js installation that is used to compile the theme's assets. +: The Node.js installation that's used to compile the theme's assets. `node_modules` : The Node.js packages that are installed to compile the theme's assets. diff --git a/news/31.feature b/news/31.feature new file mode 100644 index 0000000..ba2015d --- /dev/null +++ b/news/31.feature @@ -0,0 +1,3 @@ +Upgrade and pin Vale to v3. @stevepiercy +- Follow some of Vale's suggestions and fix errors and warnings. @stevepiercy +- Add GitHub Workflow to build docs and run checks on links, spelling, grammar, and style. @stevepiercy diff --git a/pyproject.toml b/pyproject.toml index e9eba5f..a7c5586 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,7 +64,7 @@ doc = [ "sphinxcontrib.httpexample", "sphinxcontrib-video", "sphinxext-opengraph", - "vale==2.30.0", + "vale", # Commented from Sphinx Book Theme. # Uncomment to install, then configure in conf.py. # "ablog", @@ -97,7 +97,7 @@ Repository = "https://github.com/plone/plone-sphinx-theme" Documentation = "https://github.com/plone/plone-sphinx-theme" [build-system] -requires = ["setuptools >= 69.5"] +requires = ["setuptools >= 74.0.0"] build-backend = "setuptools.build_meta" [tool.sphinx-theme-builder] diff --git a/requirements-docs.txt b/requirements-docs.txt index a5e2880..3585db9 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,18 +1,18 @@ # requirements-docs.txt -graphviz -linkify-it-py -myst-parser -plone-sphinx-theme -sphinx-autobuild -sphinx-copybutton -sphinx-design -sphinx-examples -sphinx-notfound-page -sphinx-reredirects -sphinx-sitemap -sphinxcontrib.httpdomain -sphinxcontrib.httpexample -# sphinxcontrib-mermaid # See https://github.com/mgaitan/sphinxcontrib-mermaid/issues/137 -sphinxcontrib-video -sphinxext-opengraph -vale==2.30.0 +graphviz==0.20.3 +linkify-it-py==2.0.3 +myst-parser==3.0.1 +Sphinx==7.4.7 +sphinx-autobuild==2024.4.16 +sphinx-copybutton==0.5.2 +sphinx-examples==0.0.5 +sphinx-notfound-page==1.0.0 +sphinx-reredirects==0.1.3 +sphinx-sitemap==2.6.0 +sphinx_design==0.5.0 +sphinxcontrib-httpdomain==1.8.1 +sphinxcontrib-httpexample==1.1 +# sphinxcontrib-mermaid==0.9.2 # See https://github.com/mgaitan/sphinxcontrib-mermaid/issues/137 +sphinxcontrib-video==0.2.0 +sphinxext-opengraph==0.9.1 +vale==3.7.1 diff --git a/requirements-initial.txt b/requirements-initial.txt index fda1298..288a298 100644 --- a/requirements-initial.txt +++ b/requirements-initial.txt @@ -1,5 +1,5 @@ # requirements-initial.txt # From https://dist.plone.org/release/6-latest/constraints.txt -pip==24.0 -setuptools==69.5.1 -wheel==0.43.0 +pip==24.2 +setuptools==74.0.0 +wheel==0.44.0 diff --git a/styles/Vocab/Base/accept.txt b/styles/config/vocabularies/Base/accept.txt similarity index 100% rename from styles/Vocab/Base/accept.txt rename to styles/config/vocabularies/Base/accept.txt diff --git a/styles/Vocab/Base/reject.txt b/styles/config/vocabularies/Base/reject.txt similarity index 100% rename from styles/Vocab/Base/reject.txt rename to styles/config/vocabularies/Base/reject.txt diff --git a/styles/Vocab/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt similarity index 90% rename from styles/Vocab/Plone/accept.txt rename to styles/config/vocabularies/Plone/accept.txt index 0c94f3f..ba7794e 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/config/vocabularies/Plone/accept.txt @@ -13,23 +13,28 @@ Barceloneta [Bb]oolean buildout cacheable +Code of Conduct docstrings doctest Docutils folderish fieldset +Gantt getter Graphviz JavaScript jQuery +Kitchen Sink Mockup multilanguage multiversion +MyST Netlify npm nvm Pastanaga Plone +Plone Sphinx Theme pluggab(le|ility) programatically [Pp]ortlet diff --git a/styles/Vocab/Plone/reject.txt b/styles/config/vocabularies/Plone/reject.txt similarity index 100% rename from styles/Vocab/Plone/reject.txt rename to styles/config/vocabularies/Plone/reject.txt