From d25d630eb909ce84f78b301c0bab5d054026846b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 23:22:50 -0800 Subject: [PATCH 1/4] Remove Netlify stuff, follow up to #545 - Sort and remove duplicate entries in `pyproject.toml` - Remove unused docs requirements. - Fix comments and remove unnecessary steps from `tox.ini`. - Enable copy button for code blocks. - Add linkcheck to documentation of documentation. --- .meta.toml | 1 - docs/conf.py | 1 + docs/contribute.md | 6 ++++++ netlify.toml | 5 ----- pyproject.toml | 16 +++++++--------- requirements-docs.txt | 7 ------- tox.ini | 8 ++------ 7 files changed, 16 insertions(+), 28 deletions(-) delete mode 100644 netlify.toml diff --git a/.meta.toml b/.meta.toml index 79351086..621ba0c4 100644 --- a/.meta.toml +++ b/.meta.toml @@ -19,7 +19,6 @@ check_manifest_ignores = """ "constraints.txt", "fix-converted-myst.py", "Makefile", - "netlify.toml", "requirements-docs.txt", "requirements.txt", """ diff --git a/docs/conf.py b/docs/conf.py index c20fbc67..25955cbd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,6 +24,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx.ext.viewcode", + "sphinx_copybutton", ] master_doc = "index" diff --git a/docs/contribute.md b/docs/contribute.md index cf05e211..c32850a0 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -121,6 +121,12 @@ Alternatively, you can automatically reload changes to the documentation as you tox -e livehtml ``` +You can run a link checker on documentation. + +```shell +tox -e linkcheck +``` + The [`plone.api` documentation](https://6.docs.plone.org/plone.api) is automatically generated from the documentation source files when its submodule is updated in the [main Plone `documentation` repository](https://github.com/plone/documentation/). ## Add a function to an existing module diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 9d440d0e..00000000 --- a/netlify.toml +++ /dev/null @@ -1,5 +0,0 @@ -[build.environment] - PYTHON_VERSION = "3.8" - -[build] - ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ./docs/" diff --git a/pyproject.toml b/pyproject.toml index 2066aabf..1070bc63 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -133,24 +133,22 @@ ignore-packages = ['Products.PrintingMailHost', 'plone.app.iterate',] [tool.check-manifest] ignore = [ + "*.cfg", ".editorconfig", ".flake8", ".meta.toml", ".pre-commit-config.yaml", - "dependabot.yml", - "mx.ini", - "tox.ini", - ".editorconfig", - "*.cfg", + ".readthedocs.yaml", + "Makefile", + "constraints.txt", "constraints_plone52.txt", "constraints_plone60.txt", - "constraints.txt", + "dependabot.yml", "fix-converted-myst.py", - "Makefile", - "netlify.toml", + "mx.ini", "requirements-docs.txt", "requirements.txt", - + "tox.ini", ] ## diff --git a/requirements-docs.txt b/requirements-docs.txt index 694c282c..b0d1550c 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,12 +1,5 @@ -lesscpy linkify-it-py myst-parser plone-sphinx-theme sphinx-autobuild sphinx-copybutton -sphinx-sitemap -sphinx-togglebutton -sphinxcontrib-spelling -sphinxext-opengraph -sphinxcontrib-video -vale==2.30.0 diff --git a/tox.ini b/tox.ini index eb6b27ae..8c18222e 100644 --- a/tox.ini +++ b/tox.ini @@ -255,7 +255,7 @@ allowlist_externals = echo [testenv:plone6docs] -# New docs with sphinx-book-theme +# New docs with plone-sphinx-theme # See [testenv:docs] for classic documentation basepython = python3.11 skip_install = False @@ -272,13 +272,9 @@ commands = sphinx-build -b html -d _build/plone6docs/doctrees docs _build/plone6docs/html [testenv:rtd-preview] -# New docs with sphinx-book-theme -# See [testenv:docs] for classic documentation +# Build docs on Read the Docs to preview pull requests using plone-sphinx-theme basepython = python3.11 skip_install = False -package = editable -allowlist_externals = - mkdir extras = tests deps = From b1a021becb89c5a429e504b02be6011a2aec81dd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 23:25:06 -0800 Subject: [PATCH 2/4] news --- news/546.documentation | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 news/546.documentation diff --git a/news/546.documentation b/news/546.documentation new file mode 100644 index 00000000..c1276eaf --- /dev/null +++ b/news/546.documentation @@ -0,0 +1,6 @@ +Remove Netlify stuff, follow up to #545. @stevepiercy +- Sort and remove duplicate entries in `pyproject.toml` +- Remove unused docs requirements. +- Fix comments and remove unnecessary steps from `tox.ini`. +- Enable copy button for code blocks. +- Add linkcheck to documentation of documentation. From 49050178d0847cbd335b3767197b903d5a6efff0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 18 Dec 2024 01:17:03 -0800 Subject: [PATCH 3/4] Use the correct theme --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 25955cbd..1519ad67 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -83,7 +83,7 @@ def __getattr__(cls, name): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_book_theme" +html_theme = "plone_sphinx_theme" # -- Intersphinx configuration ---------------------------------- From db089b9cbd63ab7742764c6b8f238547fba59b0f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 5 Jan 2025 17:42:09 -0800 Subject: [PATCH 4/4] - Move `tox.ini` for documentation configuration into `.meta.toml`. - Revert sort of `.gitignore` and add `.readthedocs.yaml` to the correct stanza in `.meta.toml`. --- .meta.toml | 33 +++++++++++++++++++++++++++++++-- pyproject.toml | 14 ++++++++------ 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/.meta.toml b/.meta.toml index 621ba0c4..38a7e0aa 100644 --- a/.meta.toml +++ b/.meta.toml @@ -12,8 +12,10 @@ codespell_extra_lines = """ [pyproject] check_manifest_ignores = """ - ".editorconfig", + # From `.meta.toml`, pyproject.check_manifest_ignores. "*.cfg", + ".editorconfig", + ".readthedocs.yaml", "constraints_plone52.txt", "constraints_plone60.txt", "constraints.txt", @@ -76,7 +78,7 @@ allowlist_externals = echo [testenv:plone6docs] -# New docs with sphinx-book-theme +# New docs with plone-sphinx-theme # See [testenv:docs] for classic documentation basepython = python3.11 skip_install = False @@ -92,6 +94,18 @@ commands = mkdir -p {toxinidir}/_build/plone6docs sphinx-build -b html -d _build/plone6docs/doctrees docs _build/plone6docs/html +[testenv:rtd-preview] +# Build docs on Read the Docs to preview pull requests using plone-sphinx-theme +basepython = python3.11 +skip_install = False +extras = + tests +deps = + -r requirements-docs.txt +commands = + python -VV + sphinx-build -b html -d "{env:READTHEDOCS_OUTPUT}"/doctrees/ docs "{env:READTHEDOCS_OUTPUT}"/html/ + [testenv:docs] basepython = python3.9 skip_install = False @@ -126,6 +140,21 @@ commands = python -VV mkdir -p {toxinidir}/_build/plone6docs sphinx-build -b linkcheck -d _build/plone6docs/doctrees docs _build/plone6docs/linkcheck + +[testenv:livehtml] +basepython = python3.11 +skip_install = False +package = editable +allowlist_externals = + mkdir +extras = + {[testenv:plone6docs]extras} +deps = + {[testenv:plone6docs]deps} +commands = + python -VV + mkdir -p {toxinidir}/_build/plone6docs + sphinx-autobuild -b html -d _build/plone6docs/doctrees docs _build/plone6docs/html """ [github] diff --git a/pyproject.toml b/pyproject.toml index 1070bc63..b97216f1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -133,22 +133,24 @@ ignore-packages = ['Products.PrintingMailHost', 'plone.app.iterate',] [tool.check-manifest] ignore = [ - "*.cfg", ".editorconfig", ".flake8", ".meta.toml", ".pre-commit-config.yaml", + "dependabot.yml", + "mx.ini", + "tox.ini", + "*.cfg", + ".editorconfig", ".readthedocs.yaml", - "Makefile", - "constraints.txt", "constraints_plone52.txt", "constraints_plone60.txt", - "dependabot.yml", + "constraints.txt", "fix-converted-myst.py", - "mx.ini", + "Makefile", "requirements-docs.txt", "requirements.txt", - "tox.ini", + ] ##