Build docs PR preview on RTD

.gitignore

@@ -4,15 +4,8 @@
 .cache
 .coverage
 .devenv*
-.eggs/
-.idea/
-.installed.cfg
 .pre-commit-config.yaml
-.pytest_cache/
-bin/
-devenv.local.nix
-docs/_build/
-html/
-htmlcov/
-result
+.eggs/
+_build/
 coverage.xml
+devenv.local.nix

Makefile

@@ -1,33 +1,90 @@
-help:
+# Makefile for Sphinx documentation
+.DEFAULT_GOAL   = help
+SHELL           = bash
+
+# You can set these variables from the command line.
+SPHINXOPTS      ?=
+PAPER           ?=
+
+# Internal variables.
+ifdef IN_NIX_SHELL
+BIN_FOLDER      = $(shell dirname "$$(command -v python)")
+VENV_FOLDER     = $(shell dirname "$(BIN_FOLDER)")
+else
+VENV_FOLDER     = ./.venv
+BIN_FOLDER      = $(VENV_FOLDER)/bin
+endif
+DOCS_DIR        = ./docs/
+BUILDDIR        = ../_build
+SPHINXBUILD     = "$(realpath $(BIN_FOLDER)/sphinx-build)"
+SPHINXAUTOBUILD = "$(realpath $(BIN_FOLDER)/sphinx-autobuild)"
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+PYTHONVERSION   = >=3.11,<3.15
+
+# Add the following 'help' target to your Makefile
+# And add help text after each target name starting with '\#\#'
+.PHONY: help
+help:  ## This help message
 	@grep -Eh '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' | uniq
 
 SPHINX ?= 8.3.2
-PYTHON ?= python39
+PYTHON ?= python313
+
+# environment management
+.PHONY: dev
+dev:  ## Install required Python, create Python virtual environment, and install package requirements
+	@uv python install "$(PYTHONVERSION)"
+	@uv venv --python "$(PYTHONVERSION)"
+	@uv sync
+
+.PHONY: sync
+sync:  ## Sync package requirements
+	@uv sync
+
+.PHONY: init
+init: clean clean-python dev  ## Clean docs build directory and initialize Python virtual environment
 
 .PHONY: clean
-clean:  ## Clean up build artifacts
-	rm -rf devenv.local.nix
+clean:  ## Clean docs build directory
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
 
-.PHONY: docs
-docs:  ## Build docs
-	PYTHONPATH=$(PWD)/docs sphinx-build -b html docs docs/html
+.PHONY: clean-python
+clean-python: clean
+	rm -rf .venv/
+# /environment management
 
+
+# documentation builders
+.PHONY: html
+html: dev  ## Build html
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: livehtml
+livehtml: dev  ## 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)
+# /documentation builders
+
+
+# development and contributing
 .PHONY: format
 format:  ## Format code
 	treefmt
 
-.PHONY: watch
-watch:  ## Watch build docs
-	PYTHONPATH=$(PWD)/docs sphinx-autobuild -b html docs docs/html
-
 .PHONY: show
 show:  ## Show installed packages
 	@python --version
 	@python -c "from importlib import metadata; print('\n'.join(sorted(d.metadata['Name'] + f' {d.version}' for d in metadata.distributions() if d.metadata['Name'].lower() in ['docutils', 'sphinx'])))"
 
 .PHONY: test
 test: ## Run tests
-	PYTHONPATH=$(PWD)/docs pytest --cov sphinxcontrib.httpexample tests
+	PYTHONPATH=$(DOCS_DIR) $(BIN_FOLDER)/pytest --cov sphinxcontrib.httpexample tests
 
 .PHONY: devenv-%
 devenv-%: devenv.local.nix
@@ -36,8 +93,6 @@ devenv-%: devenv.local.nix
 shell: devenv.local.nix  ## Start a shell with the development environment
 	devenv shell
 
-###
-
 htmlcov: .coverage
 	coverage html
 
@@ -70,3 +125,4 @@ test\ all:  ## Test all supported versions
 
 devenv.local.nix:
 	@echo '{ pkgs, ...}: { languages.python = { interpreter = pkgs.$(PYTHON); dependencies = [ "sphinx$(subst .,,$(SPHINX))" "dev" ]; }; }' > devenv.local.nix
+# /development and contributing

README.md

@@ -1,71 +1,95 @@
-sphinxcontrib-httpexample
-=========================
+# sphinxcontrib-httpexample
 
-.. image:: https://github.com/collective/sphinxcontrib-httpexample/actions/workflows/build.yml/badge.svg?branch=master
-   :target: https://github.com/collective/sphinxcontrib-httpexample/actions
+<img alt="GitHub Actions" src="https://github.com/collective/sphinxcontrib-httpexample/actions/workflows/build.yml/badge.svg?branch=master" href="https://github.com/collective/sphinxcontrib-httpexample/actions">
+<img alt="Coverage" src="https://coveralls.io/repos/github/collective/sphinxcontrib-httpexample/badge.svg?branch=master" href="https://coveralls.io/github/collective/sphinxcontrib-httpexample?branch=master">
+<img alt="PyPI package" src="https://badge.fury.io/py/sphinxcontrib-httpexample.svg" href="https://badge.fury.io/py/sphinxcontrib-httpexample">
+<img alt="Documentation" src="https://readthedocs.org/projects/sphinxcontrib-httpexample/badge/?version=latest" href="http://sphinxcontrib-httpexample.readthedocs.io/en/latest">
 
-.. image:: https://coveralls.io/repos/github/collective/sphinxcontrib-httpexample/badge.svg?branch=master
-   :target: https://coveralls.io/github/collective/sphinxcontrib-httpexample?branch=master
+sphinxcontrib-httpexample enhances [`sphinxcontrib-httpdomain`](https://pythonhosted.org/sphinxcontrib-httpdomain/), a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.
 
-.. image:: https://badge.fury.io/py/sphinxcontrib-httpexample.svg
-   :target: https://badge.fury.io/py/sphinxcontrib-httpexample
+The audience for this extension are developers and technical writes documenting their RESTful HTTP APIs. This extension has originally been developed for documenting [`plone.restapi`](https://6.docs.plone.org/plone.restapi/docs/source/index.html).
 
-.. image:: https://readthedocs.org/projects/sphinxcontrib-httpexample/badge/?version=latest
-   :target: http://sphinxcontrib-httpexample.readthedocs.io/en/latest
 
-sphinxcontrib-httpexample enhances `sphinxcontrib-httpdomain`_, a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.
+## Features
 
-The audience for this extension are developers and technical writes documenting their RESTful HTTP APIs. This extension has originally been developed for documenting `plone.restapi`_.
+-   Directive for generating various RESTful HTTP API call examples from single HTTP request.
+-   Supported tools:
 
-.. _sphinxcontrib-httpdomain: https://pythonhosted.org/sphinxcontrib-httpdomain/
-.. _plone.restapi: http://plonerestapi.readthedocs.org/
+    -   [curl](https://curl.haxx.se/)
+    -   [wget](https://www.gnu.org/software/wget/)
+    -   [httpie](https://httpie.org/)
+    -   [python-requests](http://docs.python-requests.org/)
 
 
-Features
---------
+## Examples
 
-* Directive for generating various RESTful HTTP API call examples from single HTTP request.
+This extension has been used at least in the following documentations:
 
-* Supported tools:
+-   https://6.docs.plone.org/plone.restapi/docs/source/index.html
+-   https://sphinxcontrib-httpexample.readthedocs.org/en/latest/
+-   https://guillotina.readthedocs.io/en/latest/
 
-  - curl_
-  - wget_
-  - httpie_
-  - python-requests_
 
-.. _curl: https://curl.haxx.se/
-.. _wget: https://www.gnu.org/software/wget/
-.. _httpie: https://httpie.org/
-.. _python-requests: http://docs.python-requests.org/
+## Documentation
 
+Full documentation for end users can be found in the "docs" folder. It is also available online at http://sphinxcontrib-httpexample.readthedocs.org/
 
-Examples
---------
 
-This extension has been used at least in the following documentations:
+## Installation
 
-* http://plonerestapi.readthedocs.org/
-* http://sphinxcontrib-httpexample.readthedocs.org/
-* https://guillotina.readthedocs.io/en/latest/
+Add `sphinxcontrib-httpexample` and `sphincontrib-httpdomain` into your project requirements.
 
+Then configure your Sphinx configuration file `conf.py` with `sphinxcontrib.httpdomain` and `sphinxcontrib.httpexample` as follows.
 
-Documentation
--------------
+```python
+extensions = [
+    "sphinxcontrib.httpdomain",
+    "sphinxcontrib.httpexample",
+]
+```
 
-Full documentation for end users can be found in the "docs" folder. It is also available online at http://sphinxcontrib-httpexample.readthedocs.org/
 
+## Contribute
+
+To contribute to `sphinxcontrib-httpexample`, first set up your environment.
+
+
+### Set up development environment
+
+Install [uv](https://6.docs.plone.org/glossary.html#term-uv).
+Carefully read the console output for further instructions, and follow them, if needed.
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Initialize a Python virtual environment.
+
+```shell
+uv venv
+```
+
+Install `sphinxcontrib-httpexample`.
+
+```shell
+uv sync
+```
+
+### Build documentation
+
+Rebuild Sphinx documentation on changes, with live-reload in the browser
 
-Installation
-------------
+```shell
+make livehtml
+```
 
-Add sphinxcontrib-httpexample into requirements of your product documentation and into the configuration file of your Sphinx documentation next to sphincontrib-httpdomain as follows:
+To stop the preview, type `CTRL-C`.
 
-..  code:: python
 
-    extensions = ['sphinxcontrib.httpdomain', 'sphinxcontrib.httpexample']
+### Run tests
 
+make te
 
-License
--------
+## License
 
 The project is licensed under the GPLv2.