From f6608adffe13cc65684efc68592ce867e3237049 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2024 00:26:29 -0700 Subject: [PATCH 1/2] - Purged unused and broken build targets. - Categorized targets with comments. - Add test requirement `sphinx.ext.doctest` so that `make doctest` will work in some Plone projects. - Add targets to correctly install, clean, and initialize the project. - Switch to `uv` from `pip`. - Fixed which changed files will build docs on RTD. - Use a replacement for supported Python versions. - Updated documentation with correct make commands. - Move release command from `README.md` to `contribute.md`. --- .github/workflows/test.yml | 1 + .gitignore | 1 + .readthedocs.yaml | 2 +- Makefile | 198 ++++++++------------ README.md | 18 +- docs/conf.py | 6 +- docs/guides/contribute.md | 16 +- docs/guides/contributing-policies.md | 2 +- docs/guides/develop.md | 1 + docs/guides/usage.md | 12 +- docs/index.md | 2 +- pyproject.toml | 34 ++-- requirements-dev.txt | 268 +++++++++++++++++++++++++++ requirements-docs.txt | 160 +++++++++++++++- requirements-initial.txt | 5 - requirements.txt | 84 +++++++++ 16 files changed, 623 insertions(+), 187 deletions(-) create mode 100644 requirements-dev.txt delete mode 100644 requirements-initial.txt create mode 100644 requirements.txt diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d2877dc..cae0955 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -14,6 +14,7 @@ on: - '.github/workflows/test.yml' - '.readthedocs.yaml' - '.vale.ini' + - 'requirements.txt' - 'requirements-docs.txt' jobs: diff --git a/.gitignore b/.gitignore index 1238be2..ec190f3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ __pycache__ +/.lock /.nodeenv /_build /bin diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0a51858..08059df 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,7 +18,7 @@ build: # If there are no changes (git diff exits with 0) we force the command to return with 183. # This is a special exit code on Read the Docs that will cancel the build immediately. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements-docs.txt; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements.txt requirements-docs.txt; then exit 183; fi diff --git a/Makefile b/Makefile index 62eb8f5..b8b5056 100644 --- a/Makefile +++ b/Makefile @@ -25,197 +25,147 @@ VALEOPTS ?= help: # This help message @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' +# environment management +.PHONY: bin/python +bin/python: ## Create Python virtual environment and install package requirements + python3 -m venv . + bin/pip install --upgrade pip setuptools uv wheel + bin/uv pip install -r requirements.txt + +.PHONY: docs +docs: bin/python ## Install documentation requirements into Python virtual environment + bin/uv pip install -r requirements-docs.txt -e . + +.PHONY: dev +dev: docs ## Install development requirements into Python virtual environment + bin/uv pip install -r requirements-dev.txt -e . + +.PHONY: update-deps +update-deps: ## Update + bin/uv pip install --upgrade pip setuptools uv wheel + bin/uv pip compile --upgrade pyproject.toml -o requirements.txt + bin/uv pip compile --upgrade pyproject.toml \ + --extra docs -o requirements-docs.txt + bin/uv pip compile --upgrade pyproject.toml \ + --extra docs --extra dev -o requirements-dev.txt + +.PHONY: init +init: clean clean-python docs ## Clean docs build directory and initialize Python virtual environment + bin/uv pip install -r requirements.txt -r requirements-docs.txt -r requirements-dev.txt -e . + bin/uv pip check + .PHONY: clean clean: ## Clean docs build directory cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ -.PHONY: distclean -distclean: ## Clean docs build directory and Python virtual environment - cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ +.PHONY: clean-python +clean-python: clean rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg +# /environment management -bin/python: ## Create Python virtual environment and install requirements - python3 -m venv . - bin/pip install ".[initial]" - bin/pip install ".[doc]" - -dev: bin/python ## - bin/pip install ".[dev]" - bin/pip install -e . - +# documentation builders .PHONY: html html: bin/python ## Build html cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -.PHONY: manual -manual: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . $(BUILDDIR)/manual +.PHONY: livehtml +livehtml: docs ## Rebuild Sphinx documentation on changes, with live-reload in the browser + cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \ + --ignore "*.swp" \ + --port 8050 \ + -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) .PHONY: dirhtml -dirhtml: bin/python +dirhtml: docs cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." .PHONY: singlehtml -singlehtml: bin/python +singlehtml: docs cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." -.PHONY: pickle -pickle: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MasteringPlone.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MasteringPlone.qhc" - -.PHONY: devhelp -devhelp: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/MasteringPlone" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MasteringPlone" - @echo "# devhelp" - -.PHONY: epub -epub: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: latex -latex: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - .PHONY: text -text: bin/python +text: docs cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." -.PHONY: man -man: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: bin/python - cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - .PHONY: changes -changes: bin/python +changes: docs cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." +# /documentation builders +# test .PHONY: linkcheck -linkcheck: bin/python ## Run linkcheck +linkcheck: docs ## Run linkcheck cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/ ." .PHONY: linkcheckbroken -linkcheckbroken: bin/python ## Run linkcheck and show only broken links +linkcheckbroken: docs ## Run linkcheck and show only broken links cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? = 0; then exit 1; fi || test $$? = 1 @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/ ." .PHONY: vale -vale: bin/python ## Run Vale style, grammar, and spell checks +vale: docs dev ## Run Vale style, grammar, and spell checks bin/vale sync bin/vale --no-wrap $(VALEOPTS) $(VALEFILES) @echo @echo "Vale is finished; look for any errors in the above output." -.PHONY: html_meta -html_meta: bin/python ## Add meta data headers to all Markdown pages - python ./docs/addMetaData.py - .PHONY: doctest -doctest: bin/python +doctest: docs ## Test snippets in the documentation cd $(DOCS_DIR) && $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." .PHONY: test -test: clean linkcheckbroken ## Clean docs build, then run linkcheckbroken +test: clean vale linkcheckbroken doctest ## Clean docs build, then run vale and linkcheckbroken +# /test -.PHONY: deploy -deploy: clean html - -.PHONY: livehtml -livehtml: bin/python ## Rebuild Sphinx documentation on changes, with live-reload in the browser - cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \ - --ignore "*.swp" \ - --port 8050 \ - -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) +# development +.PHONY: html_meta +html_meta: docs ## Add meta data headers to all Markdown pages + python ./docs/addMetaData.py -serve: ## Compile static assets, build and serve the docs, and reload the browser on changes - bin/stb serve docs/ +.PHONY: kitchen-sink-update +kitchen-sink-update: ## Copy Kitchen Sink documentation files to Plone Sphinx Theme + bin/python scripts/kitchen_sink_update.py .PHONY: sbt-styles-update sbt-styles-update: ## Copy Sphinx Book Theme styles to Plone Sphinx Theme bin/python scripts/sbt_styles_update.py -.PHONY: kitchen-sink-update -kitchen-sink-update: ## Copy Kitchen Sink documentation files to Plone Sphinx Theme - bin/python scripts/kitchen_sink_update.py +.PHONY: serve +serve: ## Compile static assets, build and serve the docs, and reload the browser on changes + bin/stb serve docs/ + +.PHONY: compile +compile: ## Compile static assets + bin/stb compile .PHONY: rtd-pr-preview -rtd-pr-preview: bin/python ## Build pull request preview on Read the Docs +rtd-pr-preview: docs ## Build pull request preview on Read the Docs cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ +.PHONY: release +release: dev compile ## Release with zest.releaser + bin/fullrelease + .PHONY: all all: clean vale linkcheck html ## Clean docs build, then run vale and linkcheck, and build html +# /development + +.PHONY: deploy +deploy: clean html diff --git a/README.md b/README.md index 6a8de4f..b8cb186 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ It is based on [`sphinx-book-theme`](https://sphinx-book-theme.readthedocs.io/en ## Requirements - Python 3.9, 3.10, 3.11, or 3.12 -- GNU Make is required only for contributing to or development of this theme. +- GNU Make is required only for building the documentation, contributing to, or development of this theme. ## Documentation @@ -16,19 +16,3 @@ It is based on [`sphinx-book-theme`](https://sphinx-book-theme.readthedocs.io/en Documentation is hosted on Read the Docs. https://plone-sphinx-theme.readthedocs.io/ - - -## Demonstration - -TODO: Add reference to documentation permanent URL. - -To build documentation and a demonstration of this project, you can use `make` commands. - - -## Releasing - -Run the following command. - -```shell -fullrelease -``` diff --git a/docs/conf.py b/docs/conf.py index 2323205..316316f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,7 @@ "notfound.extension", "sphinx.ext.autodoc", "sphinx.ext.autosummary", # plone.api + "sphinx.ext.doctest", # plone.api "sphinx.ext.graphviz", "sphinx.ext.ifconfig", "sphinx.ext.intersphinx", @@ -96,6 +97,7 @@ r"https://github.com/orgs/plone/teams/", # requires auth r"https://github.com/plone/documentation/issues/new/choose", # requires auth r"https://github.com/plone/volto/issues/new/choose", # requires auth + r"https://github.com/plone/plone-sphinx-theme/issues/new", # requires auth # Ignore github.com pages with anchors r"https://github.com/.*#.*", # Ignore other specific anchors @@ -406,9 +408,9 @@ def source_replace(app, docname, source): # Dict of replacements. source_replacements = { "{PLONE_BACKEND_MINOR_VERSION}": "6.0", - "{PLONE_BACKEND_PATCH_VERSION}": "6.0.11", + "{PLONE_BACKEND_PATCH_VERSION}": "6.0.13", "{NVM_VERSION}": "0.39.5", - "{SUPPORTED_PYTHON_VERSIONS}": "3.8, 3.9, 3.10, 3.11, or 3.12", + "{SUPPORTED_PYTHON_VERSIONS}": "3.9, 3.10, 3.11, or 3.12", } diff --git a/docs/guides/contribute.md b/docs/guides/contribute.md index a3091fa..1ae019e 100644 --- a/docs/guides/contribute.md +++ b/docs/guides/contribute.md @@ -12,9 +12,10 @@ myst: This document describes how to install Plone Sphinx Theme for contributing code to this project, and what you can modify. 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>` +- Python {SUPPORTED_PYTHON_VERSIONS} - {term}`GNU Make` @@ -103,7 +104,7 @@ See {ref}`update-parent-theme-styles` for details. After editing any of the static assets, you need to compile them. ```shell -stb compile +make compile ``` @@ -124,3 +125,14 @@ make sbt-styles-update Plone Sphinx Theme uses webpack to compile a JavaScript file for its theme. You can edit these files located in the directory {file}`src/plone_sphinx_theme/assets/scripts`. + + +## Release + +To release Plone Sphinx Theme, use the following command. + +```shell +make release +``` + +This command runs [`zest.releaser`](https://pypi.org/project/zest.releaser/) to make a full release. diff --git a/docs/guides/contributing-policies.md b/docs/guides/contributing-policies.md index 23c3ac7..b3aa5f4 100644 --- a/docs/guides/contributing-policies.md +++ b/docs/guides/contributing-policies.md @@ -32,7 +32,7 @@ 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. -If accepted, your GitHub account will be added to a team in the Plone GitHub organization with appropriate access, and you will simultaneously receive an email notification from GitHub. +If accepted, your GitHub account will be added to a team in the Plone GitHub organization with appropriate access, and you will simultaneously receive an email from GitHub for you to accept the invitation to join the team. Allow up to one week for processing. Contact the Plone Foundation by its email address for further information, including the status of your request. diff --git a/docs/guides/develop.md b/docs/guides/develop.md index bfc2233..008a3c2 100644 --- a/docs/guides/develop.md +++ b/docs/guides/develop.md @@ -9,6 +9,7 @@ myst: # Develop your own theme + ```{todo} This document is a work in progress. Currently it only lists the files that need to be customized for your own theme, and not how to customize them. diff --git a/docs/guides/usage.md b/docs/guides/usage.md index 772a967..4525e7f 100644 --- a/docs/guides/usage.md +++ b/docs/guides/usage.md @@ -20,7 +20,7 @@ To develop your own theme based upon Plone Sphinx Theme, see {doc}`develop`. ## Prerequisites -- Install a supported version of Python, as specified on this documentation's {doc}`home page <../index>`. +- Python {SUPPORTED_PYTHON_VERSIONS}. - Create a Python virtual environment for your project, and optionally activate it. The following commands assume you have activated your virtual environment. @@ -36,13 +36,13 @@ To develop your own theme based upon Plone Sphinx Theme, see {doc}`develop`. ```toml [project.optional-dependencies] - doc = [ + docs = [ "plone-sphinx-theme", ] ``` ```` - ````{tab-item} requirements-doc.txt + ````{tab-item} requirements-docs.txt :sync: key2 ```text plone-sphinx-theme @@ -58,14 +58,14 @@ To develop your own theme based upon Plone Sphinx Theme, see {doc}`develop`. ````{tab-item} pyproject.toml :sync: key1 ```shell - pip install my_project[doc] + pip install my_project[docs] ``` ```` - ````{tab-item} requirements-doc.txt + ````{tab-item} requirements-docs.txt :sync: key2 ```shell - pip install -r requirements-doc.txt + pip install -r requirements-docs.txt ``` ```` diff --git a/docs/index.md b/docs/index.md index 09f1be2..85b7807 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ myst: It uses [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/), a rich and extensible flavor of Markdown for authoring documentation that combines the simplicity of CommonMark with the features of reStructuredText. -Plone Sphinx Theme requires Python 3.9, 3.10, 3.11, or 3.12. +Plone Sphinx Theme requires Python {SUPPORTED_PYTHON_VERSIONS}. ```{todo} diff --git a/pyproject.toml b/pyproject.toml index a7c5586..39bceaf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,13 +11,7 @@ keywords = [ ] dynamic = ["version"] readme = "README.md" - -requires-python = ">=3.9" -dependencies = [ - "sphinx>=7", - "sphinx-book-theme>=1.1.2", -] - +requires-python = ">=3.9,<3.13" license = { file = "LICENSE" } maintainers = [ { name = "Steve Piercy", email = "spiercy@plone.org" }, @@ -39,24 +33,24 @@ classifiers = [ "Programming Language :: Python :: 3.12", ] +dependencies = [ + "myst-parser==3.0.1", # Supports Python 3.9-3.12, which is what we need for Plone 6.0. Consider bumping for Plone 6.1. + "sphinx==7.4.7", # Supports Python 3.9-3.12, which is what we need for Plone 6.0. Consider bumping for Plone 6.1. + "sphinx-book-theme", +] + [project.optional-dependencies] #code_style = [ # "pre-commit" #] -initial = [ - # From https://dist.plone.org/release/6-latest/constraints.txt - "pip==24.0", - "setuptools==69.5.1", - "wheel==0.43.0", -] -doc = [ +docs = [ "graphviz", "linkify-it-py", - "myst-parser", "sphinx-autobuild", "sphinx-copybutton", "sphinx-design", "sphinx-examples", +# "sphinxcontrib-mermaid==0.9.2", # See https://github.com/mgaitan/sphinxcontrib-mermaid/issues/137 "sphinx-notfound-page", "sphinx-reredirects", "sphinx-sitemap", @@ -64,7 +58,7 @@ doc = [ "sphinxcontrib.httpexample", "sphinxcontrib-video", "sphinxext-opengraph", - "vale", + # Commented from Sphinx Book Theme. # Uncomment to install, then configure in conf.py. # "ablog", @@ -84,7 +78,11 @@ doc = [ # "sphinxcontrib-youtube", ] dev = [ + # Development "sphinx-theme-builder[cli]", + # Test + "vale", + # Release "zest.releaser[recommended]", "zestreleaser.towncrier", ] @@ -94,10 +92,10 @@ dev = [ [project.urls] Repository = "https://github.com/plone/plone-sphinx-theme" -Documentation = "https://github.com/plone/plone-sphinx-theme" +Documentation = "https://plone-sphinx-theme.readthedocs.io/" [build-system] -requires = ["setuptools >= 74.0.0"] +requires = ["setuptools"] build-backend = "setuptools.build_meta" [tool.sphinx-theme-builder] diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..5b19089 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,268 @@ +# This file was autogenerated by uv via the following command: +# uv pip compile pyproject.toml --extra docs --extra dev -o requirements-dev.txt +accessible-pygments==0.0.5 + # via pydata-sphinx-theme +alabaster==0.7.16 + # via sphinx +anyio==4.6.0 + # via + # starlette + # watchfiles +astunparse==1.6.3 + # via sphinxcontrib-httpexample +babel==2.16.0 + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.12.3 + # via pydata-sphinx-theme +build==1.2.2.post1 + # via + # check-manifest + # pyroma + # sphinx-theme-builder + # zest-releaser +certifi==2024.8.30 + # via requests +cffi==1.17.1 + # via cmarkgfm +charset-normalizer==3.3.2 + # via requests +check-manifest==0.49 + # via zest-releaser +click==8.1.7 + # via + # sphinx-theme-builder + # towncrier + # uvicorn +cmarkgfm==2024.1.14 + # via readme-renderer +colorama==0.4.6 + # via + # sphinx-autobuild + # zest-releaser +docutils==0.21.2 + # via + # myst-parser + # pydata-sphinx-theme + # pyroma + # readme-renderer + # sphinx + # sphinxcontrib-httpexample +graphviz==0.20.3 + # via plone-sphinx-theme (pyproject.toml) +h11==0.14.0 + # via uvicorn +idna==3.10 + # via + # anyio + # requests +imagesize==1.4.1 + # via sphinx +importlib-metadata==8.5.0 + # via twine +jaraco-classes==3.4.0 + # via keyring +jaraco-context==6.0.1 + # via keyring +jaraco-functools==4.1.0 + # via keyring +jinja2==3.1.4 + # via + # myst-parser + # sphinx + # towncrier +keyring==25.4.1 + # via twine +linkify-it-py==2.0.3 + # via plone-sphinx-theme (pyproject.toml) +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser + # rich +markupsafe==2.1.5 + # via jinja2 +mdit-py-plugins==0.4.2 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +more-itertools==10.5.0 + # via + # jaraco-classes + # jaraco-functools +myst-parser==3.0.1 + # via plone-sphinx-theme (pyproject.toml) +nh3==0.2.18 + # via readme-renderer +nodeenv==1.9.1 + # via sphinx-theme-builder +packaging==24.1 + # via + # build + # pydata-sphinx-theme + # pyproject-metadata + # pyroma + # sphinx + # sphinx-theme-builder +pep440==0.1.2 + # via zest-releaser +pkginfo==1.10.0 + # via twine +pycparser==2.22 + # via cffi +pydata-sphinx-theme==0.15.4 + # via sphinx-book-theme +pygments==2.18.0 + # via + # accessible-pygments + # pydata-sphinx-theme + # pyroma + # readme-renderer + # rich + # sphinx +pyproject-hooks==1.2.0 + # via build +pyproject-metadata==0.8.0 + # via sphinx-theme-builder +pyroma==4.2 + # via zest-releaser +pyyaml==6.0.2 + # via myst-parser +readme-renderer==44.0 + # via + # twine + # zest-releaser +requests==2.32.3 + # via + # pyroma + # requests-toolbelt + # sphinx + # twine + # zest-releaser +requests-toolbelt==1.0.0 + # via twine +rfc3986==2.0.0 + # via twine +rich==13.9.2 + # via + # sphinx-theme-builder + # twine +setuptools==75.1.0 + # via + # check-manifest + # pyroma + # sphinx-theme-builder + # zest-releaser + # zestreleaser-towncrier +six==1.16.0 + # via + # astunparse + # sphinxcontrib-httpdomain +sniffio==1.3.1 + # via anyio +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.6 + # via beautifulsoup4 +sphinx==7.4.7 + # via + # plone-sphinx-theme (pyproject.toml) + # myst-parser + # pydata-sphinx-theme + # sphinx-autobuild + # sphinx-book-theme + # sphinx-copybutton + # sphinx-design + # sphinx-examples + # sphinx-notfound-page + # sphinx-reredirects + # sphinx-sitemap + # sphinxcontrib-httpdomain + # sphinxcontrib-httpexample + # sphinxcontrib-video + # sphinxext-opengraph +sphinx-autobuild==2024.10.3 + # via + # plone-sphinx-theme (pyproject.toml) + # sphinx-theme-builder +sphinx-book-theme==1.1.3 + # via plone-sphinx-theme (pyproject.toml) +sphinx-copybutton==0.5.2 + # via plone-sphinx-theme (pyproject.toml) +sphinx-design==0.6.1 + # via + # plone-sphinx-theme (pyproject.toml) + # sphinx-examples +sphinx-examples==0.0.5 + # via plone-sphinx-theme (pyproject.toml) +sphinx-notfound-page==1.0.4 + # via plone-sphinx-theme (pyproject.toml) +sphinx-reredirects==0.1.5 + # via plone-sphinx-theme (pyproject.toml) +sphinx-sitemap==2.6.0 + # via plone-sphinx-theme (pyproject.toml) +sphinx-theme-builder==0.2.0b2 + # via plone-sphinx-theme (pyproject.toml) +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-httpdomain==1.8.1 + # via + # plone-sphinx-theme (pyproject.toml) + # sphinxcontrib-httpexample +sphinxcontrib-httpexample==1.3 + # via plone-sphinx-theme (pyproject.toml) +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx +sphinxcontrib-video==0.2.1 + # via plone-sphinx-theme (pyproject.toml) +sphinxext-opengraph==0.9.1 + # via plone-sphinx-theme (pyproject.toml) +starlette==0.39.2 + # via sphinx-autobuild +tomli==2.0.2 + # via zestreleaser-towncrier +towncrier==24.8.0 + # via zestreleaser-towncrier +trove-classifiers==2024.9.12 + # via pyroma +twine==5.1.1 + # via zest-releaser +typing-extensions==4.12.2 + # via pydata-sphinx-theme +uc-micro-py==1.0.3 + # via linkify-it-py +urllib3==2.2.3 + # via + # requests + # twine +uv==0.4.18 + # via plone-sphinx-theme (pyproject.toml) +uvicorn==0.31.0 + # via sphinx-autobuild +vale==3.7.1.0 + # via plone-sphinx-theme (pyproject.toml) +watchfiles==0.24.0 + # via sphinx-autobuild +websockets==13.1 + # via sphinx-autobuild +wheel==0.44.0 + # via + # astunparse + # zest-releaser +zest-releaser==9.2.0 + # via + # plone-sphinx-theme (pyproject.toml) + # zestreleaser-towncrier +zestreleaser-towncrier==1.3.0 + # via plone-sphinx-theme (pyproject.toml) +zipp==3.20.2 + # via importlib-metadata diff --git a/requirements-docs.txt b/requirements-docs.txt index 3585db9..aef1cd5 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,18 +1,158 @@ -# requirements-docs.txt +# This file was autogenerated by uv via the following command: +# uv pip compile pyproject.toml --extra docs -o requirements-docs.txt +accessible-pygments==0.0.5 + # via pydata-sphinx-theme +alabaster==0.7.16 + # via sphinx +anyio==4.6.0 + # via + # starlette + # watchfiles +astunparse==1.6.3 + # via sphinxcontrib-httpexample +babel==2.16.0 + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.12.3 + # via pydata-sphinx-theme +certifi==2024.8.30 + # via requests +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via uvicorn +colorama==0.4.6 + # via sphinx-autobuild +docutils==0.21.2 + # via + # myst-parser + # pydata-sphinx-theme + # sphinx + # sphinxcontrib-httpexample graphviz==0.20.3 + # via plone-sphinx-theme (pyproject.toml) +h11==0.14.0 + # via uvicorn +idna==3.10 + # via + # anyio + # requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.4 + # via + # myst-parser + # sphinx linkify-it-py==2.0.3 + # via plone-sphinx-theme (pyproject.toml) +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.5 + # via jinja2 +mdit-py-plugins==0.4.2 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py myst-parser==3.0.1 -Sphinx==7.4.7 -sphinx-autobuild==2024.4.16 + # via plone-sphinx-theme (pyproject.toml) +packaging==24.1 + # via + # pydata-sphinx-theme + # sphinx +pydata-sphinx-theme==0.15.4 + # via sphinx-book-theme +pygments==2.18.0 + # via + # accessible-pygments + # pydata-sphinx-theme + # sphinx +pyyaml==6.0.2 + # via myst-parser +requests==2.32.3 + # via sphinx +six==1.16.0 + # via + # astunparse + # sphinxcontrib-httpdomain +sniffio==1.3.1 + # via anyio +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.6 + # via beautifulsoup4 +sphinx==7.4.7 + # via + # plone-sphinx-theme (pyproject.toml) + # myst-parser + # pydata-sphinx-theme + # sphinx-autobuild + # sphinx-book-theme + # sphinx-copybutton + # sphinx-design + # sphinx-examples + # sphinx-notfound-page + # sphinx-reredirects + # sphinx-sitemap + # sphinxcontrib-httpdomain + # sphinxcontrib-httpexample + # sphinxcontrib-video + # sphinxext-opengraph +sphinx-autobuild==2024.10.3 + # via plone-sphinx-theme (pyproject.toml) +sphinx-book-theme==1.1.3 + # via plone-sphinx-theme (pyproject.toml) sphinx-copybutton==0.5.2 + # via plone-sphinx-theme (pyproject.toml) +sphinx-design==0.6.1 + # via + # plone-sphinx-theme (pyproject.toml) + # sphinx-examples sphinx-examples==0.0.5 -sphinx-notfound-page==1.0.0 -sphinx-reredirects==0.1.3 + # via plone-sphinx-theme (pyproject.toml) +sphinx-notfound-page==1.0.4 + # via plone-sphinx-theme (pyproject.toml) +sphinx-reredirects==0.1.5 + # via plone-sphinx-theme (pyproject.toml) sphinx-sitemap==2.6.0 -sphinx_design==0.5.0 + # via plone-sphinx-theme (pyproject.toml) +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx 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 + # via + # plone-sphinx-theme (pyproject.toml) + # sphinxcontrib-httpexample +sphinxcontrib-httpexample==1.3 + # via plone-sphinx-theme (pyproject.toml) +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx +sphinxcontrib-video==0.2.1 + # via plone-sphinx-theme (pyproject.toml) sphinxext-opengraph==0.9.1 -vale==3.7.1 + # via plone-sphinx-theme (pyproject.toml) +starlette==0.39.2 + # via sphinx-autobuild +typing-extensions==4.12.2 + # via pydata-sphinx-theme +uc-micro-py==1.0.3 + # via linkify-it-py +urllib3==2.2.3 + # via requests +uvicorn==0.31.0 + # via sphinx-autobuild +watchfiles==0.24.0 + # via sphinx-autobuild +websockets==13.1 + # via sphinx-autobuild +wheel==0.44.0 + # via astunparse diff --git a/requirements-initial.txt b/requirements-initial.txt deleted file mode 100644 index 288a298..0000000 --- a/requirements-initial.txt +++ /dev/null @@ -1,5 +0,0 @@ -# requirements-initial.txt -# From https://dist.plone.org/release/6-latest/constraints.txt -pip==24.2 -setuptools==74.0.0 -wheel==0.44.0 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..2b77745 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,84 @@ +# This file was autogenerated by uv via the following command: +# uv pip compile pyproject.toml -o requirements.txt +accessible-pygments==0.0.5 + # via pydata-sphinx-theme +alabaster==0.7.16 + # via sphinx +babel==2.16.0 + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.12.3 + # via pydata-sphinx-theme +certifi==2024.8.30 + # via requests +charset-normalizer==3.3.2 + # via requests +docutils==0.21.2 + # via + # myst-parser + # pydata-sphinx-theme + # sphinx +idna==3.10 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.4 + # via + # myst-parser + # sphinx +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.5 + # via jinja2 +mdit-py-plugins==0.4.2 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==3.0.1 + # via plone-sphinx-theme (pyproject.toml) +packaging==24.1 + # via + # pydata-sphinx-theme + # sphinx +pydata-sphinx-theme==0.15.4 + # via sphinx-book-theme +pygments==2.18.0 + # via + # accessible-pygments + # pydata-sphinx-theme + # sphinx +pyyaml==6.0.2 + # via myst-parser +requests==2.32.3 + # via sphinx +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.6 + # via beautifulsoup4 +sphinx==7.4.7 + # via + # plone-sphinx-theme (pyproject.toml) + # myst-parser + # pydata-sphinx-theme + # sphinx-book-theme +sphinx-book-theme==1.1.3 + # via plone-sphinx-theme (pyproject.toml) +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx +typing-extensions==4.12.2 + # via pydata-sphinx-theme +urllib3==2.2.3 + # via requests From 0650ce9700c23aa6701300be9a535d51f59e0783 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 7 Oct 2024 00:32:41 -0700 Subject: [PATCH 2/2] news --- news/33.feature | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 news/33.feature diff --git a/news/33.feature b/news/33.feature new file mode 100644 index 0000000..6620a94 --- /dev/null +++ b/news/33.feature @@ -0,0 +1,9 @@ +Purged unused and broken Make build targets. @stevepiercy +- Categorized Make targets with comments. @stevepiercy +- Add test requirement `sphinx.ext.doctest` so that `make doctest` will work in some Plone projects. @stevepiercy +- Add targets to correctly install, clean, and initialize the project. @stevepiercy +- Switch to `uv` from `pip`. @stevepiercy +- Fixed which changed files will build docs on RTD. @stevepiercy +- Use a replacement for supported Python versions. @stevepiercy +- Updated documentation with correct make commands. @stevepiercy +- Move release command from `README.md` to `contribute.md`. @stevepiercy