sphinxcontrib-httpexample 1.2__tar.gz → 2.0__tar.gz

sphinxcontrib_httpexample-2.0/.coveragerc

@@ -0,0 +1,2 @@
+[report]
+include = src/*

sphinxcontrib_httpexample-2.0/.editorconfig

@@ -0,0 +1,15 @@
+[*]
+indent_style = space
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[{*.py,*.cfg}]
+indent_size = 4
+
+[{*.html,*.dtml,*.pt,*.zpt,*.xml,*.zcml,*.js}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

sphinxcontrib_httpexample-2.0/.github/workflows/build.yml

@@ -0,0 +1,33 @@
+name: "build"
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: [python310, python311, python312, python313, python314]
+        sphinx: [8.2.3, 8.1.3, 8.0.2, 7.4.7]
+        exclude:
+          - python: python310
+            sphinx: 8.2.3
+    steps:
+    - uses: actions/checkout@v6
+    - uses: cachix/install-nix-action@v30
+      with:
+        nix_path: nixpkgs=channel:nixos-unstable
+    - uses: cachix/cachix-action@v15
+      with:
+        name: datakurre
+        signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
+        authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+    - run: nix profile install nixpkgs#devenv
+    - run: LC_ALL=en_US.UTF-8 make devenv-test devenv-coverage devenv-docs PYTHON=${{ matrix.python }} SPHINX=${{ matrix.sphinx }}
+    - uses: coverallsapp/github-action@v2
+      if: matrix.python == 'python314' && matrix.sphinx == '8.2.3'
+      with:
+        debug: true
+        format: cobertura
+        github-token: ${{ secrets.GITHUB_TOKEN }}

sphinxcontrib_httpexample-2.0/.github/workflows/rtd-pr-preview.yml

@@ -0,0 +1,23 @@
+# .github/workflows/rtd-pr-preview.yml
+# https://github.com/readthedocs/actions/blob/v1/preview/README.md
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types:
+      - opened
+    # Execute this action only on PRs that touch
+    # documentation files.
+    # paths:
+    #   - "docs/**"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "sphinxcontrib-httpexample"
+          single-version: "true"

sphinxcontrib_httpexample-2.0/.gitignore

@@ -0,0 +1,11 @@
+*.egg-info
+*.mo
+*.pyc
+.cache
+.coverage
+.devenv*
+.pre-commit-config.yaml
+.eggs/
+_build/
+coverage.xml
+devenv.local.nix

sphinxcontrib_httpexample-2.0/.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

sphinxcontrib_httpexample-2.0/.treefmt.toml

@@ -0,0 +1,13 @@
+on-unmatched = "debug"
+
+[formatter.nix]
+command = "nixfmt"
+includes = ["*.nix"]
+
+[formatter.python]
+command = "black"
+includes = ["*.py"]
+
+[formatter.isort]
+command = "isort"
+includes = ["*.py"]

sphinxcontrib_httpexample-2.0/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog
+
+## 2.0 (2026-02-23)
+
+- Dropped support for Python 3.9.
+  [stevepiercy]
+- Migrated from `pkg_resources` to `importlib`.
+  [datakurre]
+- Overhauled `Makefile`. Add `make lint` and `make test` targets.
+  [stevepiercy]
+- Use uv to set up a development environment.
+  [stevepiercy]
+- Enhanced documentation with `@plone/client` examples, clarify headings, fix broken links, and improve formatting, grammar, and syntax.
+  Added sphinx-copybutton extension to allow copying code snippets.
+  [stevepiercy]
+- Use the `name` argument for the CSS label.
+  [Hrittik20]
+- Fixed a regression so that the response tab now shows the HTTP response instead of the request.
+  [datakurre]
+
+
+## 2.0rc1 (2025-12-02)
+
+- Add support for Python 3.14
+  [datakurre]
+- Drop support for Python 2
+  [datakurre]
+
+## 1.3 (2024-08-18)
+
+- Add new directive `.. http:example-block::` to allow use with Sphinx tab libraries like
+  [sphinx-inline-tabs](https://sphinx-inline-tabs.readthedocs.io/en/latest/) or
+  [sphinx-design](https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html).
+  [AWhetter]
+
+## 1.2 (2024-08-17)
+
+- Add new HTTP example builder `plone-javascript`
+  [datakurre]
+- Fix tabbing to no longer depend on jQuery
+  [datakurre]
+- Fix tabbing to support arrow key navigation
+  [datakurre]
+- Fix tab key to stop at tab list only once
+  [datakurre]
+- Fix requests builder to flatten simple values in form data
+  [datakurre]
+- Fix requests builder to pass form data as dictionary
+  [datakurre]
+- Change JavaScript-based tabbing to no longer require JQuery
+  [datakurre]
+
+## 1.1 (2021-12-25)
+
+- Add support for docutils 0.17.x
+  [kvondersaar, datakurre]
+- Add support for Python 3.8
+  [datakurre]
+- Fix example tabs accessibility
+  [datakurre]
+
+## 1.0 (2021-09-10)
+
+- The curl command builder will now always specify a method
+  [LefterisJP]
+
+## 0.11.0 (2021-05-14)
+
+- Change to quote examples with `"` rather than `'`
+  [datakurre]
+- Fix Sphinx deprecation warnings and support Sphinx 4.x
+  [kkrypt0nn, AWhetter]
+- Fix to use `ast.unparse` instead of `astunparse` on Python >= 3.9
+  [datakurre]
+
+## 0.10.3 (2019-05-01)
+
+- Re-release 0.10.2 with wheel
+  [datakurre]
+
+## 0.10.2 (2019-05-01)
+
+- Add support for inline response examples without HTTP version
+  (e.g., `HTTP 200 OK`)
+  [datakurre]
+- Fix regression where support for reading request examples from
+  external files was broken since 0.10.0
+  [datakurre]
+
+## 0.10.1 (2019-03-19)
+
+- Fix issue where it was not possible to request examples with
+  float values in payload JSON [fixes #42]
+  [datakurre]
+
+## 0.10.0 (2018-10-09)
+
+- Add support for URL query parameters, using the `query` field.
+  Given a line `:query param_name: param_value` in an HTTP example
+  directive, the key-value pair `param_name`, `param_value` will be
+  added to the request URL (and excluded from further processing).
+  [ludaavics]
+
+  Example:
+
+  ```http
+  GET /items HTTP/1.1
+  Host: localhost
+  Accept: application/json
+  Authorization: Basic dXNlcjpwYXNzd29yZA==
+
+  :query from: 20170101
+  :query to: 20171231
+  :query user_id: 12
+  :query limit: 20
+  :query sort: date(asc)
+  ```
+
+## 0.9.1 (2018-10-06)
+
+- Fix packaging to include `setup.cfg` in sdist
+  [datakurre]
+- Add the Guillotina docs (which now uses httpexample)
+  [cdevienne]
+
+## 0.9.0 (2018-07-22)
+
+- Add support for inlining responses
+  [cdevienne]
+
+## 0.8.1 (2018-06-27)
+
+- Fix error when parsing top-level JSON lists
+  [AWhetter]
+
+## 0.8.0 (2017-11-18)
+
+- Fix to not strip out `Accept`/`Content-Type` headers in builders
+  [dokai]
+- Improve logic to detect a JSON content type
+  [dokai]
+- Use redirected input to pass request payload to `httpie`
+  [dokai]
+- Fix quoting of non-trivial HTTP headers in builders
+  [dokai]
+- Change to use declarative packaging (`setup.cfg` instead of `setup.py`)
+  [datakurre]
+
+## 0.7.0 (2017-10-21)
+
+- Allow the URL scheme (`http` or `https`) to be configured
+  [dokai]
+- Quote the URL if it contains `&` characters in `curl`/`httpie`/`wget` examples
+  [dokai]
+
+## 0.6.1 (2017-05-11)
+
+- Release as universal wheel
+  [datakurre]
+
+## 0.6.0 (2017-05-11)
+
+- Support non-JSON requests
+  [jaroel]
+- Support `application/json; charset=utf-8`
+  [skyzyx]
+
+## 0.5.2 (2017-03-09)
+
+- Fix packaging to include the files in `static` [#3]
+  [csenger]
+
+## 0.5.1 (2017-03-05)
+
+- Update README and documentation
+  [datakurre]
+
+## 0.5.0 (2017-03-05)
+
+- Change development status to beta
+  [datakurre]
+
+## 0.4.2 (2017-03-05)
+
+- Fix issue where `wget` basic auth required a challenge from the backend, which is not
+  always available
+  [datakurre]
+
+## 0.4.1 (2017-03-05)
+
+- Fix issue where generated `httpie` commands did not always set `Accept` and
+  `Content-Type` headers
+  [datakurre]
+
+## 0.4.0 (2017-03-05)
+
+- Add support for `wget`
+  [datakurre]
+
+## 0.3.0 (2017-03-05)
+
+- Add generic `Authorization` header support
+  [datakurre]
+
+## 0.2.1 (2017-03-05)
+
+- Fix issue where `Authorization` header was always required
+  [datakurre]
+- Fix to raise proper exception when parsing bad requests
+  [datakurre]
+- Fix issue where `httpie` builder did not quote values with spaces
+  [datakurre]
+- Fix link to `python-requests` documentation
+  [datakurre]
+
+## 0.2.0 (2017-03-05)
+
+- Add support for `GET` requests
+  [datakurre]
+
+## 0.1.0 (2017-03-05)
+
+- First release
+  [datakurre]

sphinxcontrib_httpexample-2.0/Makefile

@@ -0,0 +1,136 @@
+# Makefile for Sphinx documentation
+.DEFAULT_GOAL   = help
+SHELL           = bash
+
+# You can set these variables from the command line.
+SPHINXOPTS      ?=
+PAPER           ?=
+
+# Internal variables.
+MAKEFILE_DIR := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
+ifdef IN_NIX_SHELL
+BIN_FOLDER      = $(shell dirname "$$(command -v python)")
+VENV_FOLDER     = $(shell dirname "$(BIN_FOLDER)")
+else
+VENV_FOLDER     = $(MAKEFILE_DIR)/.venv
+BIN_FOLDER      = $(VENV_FOLDER)/bin
+endif
+DOCS_DIR        = $(MAKEFILE_DIR)/docs/
+BUILDDIR        = $(MAKEFILE_DIR)/_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 ?= python313
+
+# docs contains example of custom http-example builder module
+export PYTHONPATH=$(DOCS_DIR)
+
+# environment management
+.venv:  ## Install required Python, create Python virtual environment, and install package requirements
+ifndef IN_NIX_SHELL
+	@uv python install "$(PYTHONVERSION)"
+	@uv venv --python "$(PYTHONVERSION)"
+	@uv sync
+endif
+
+.PHONY: sync
+sync:  ## Sync package requirements
+ifndef IN_NIX_SHELL
+	@uv sync
+endif
+
+.PHONY: init
+init: clean clean-python .venv  ## Clean docs build directory and initialize Python virtual environment
+
+.PHONY: clean
+clean:  ## Clean docs build directory
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+
+.PHONY: clean-python
+clean-python: clean
+	rm -rf .venv/
+# /environment management
+
+
+# documentation builders
+.PHONY: html
+html: .venv  ## 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: .venv  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
+		--ignore "*.swp" \
+		--watch "../src/sphinxcontrib/httpexample/" \
+		--port 8050 \
+		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+# /documentation builders
+
+
+# development and contributing
+.PHONY: format
+format:  ## Format code
+	treefmt
+
+.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
+	$(BIN_FOLDER)/pytest --cov sphinxcontrib.httpexample tests
+
+.PHONY: devenv-%
+devenv-%: devenv.local.nix
+	devenv shell $(MAKE) $*
+
+shell: devenv.local.nix  ## Start a shell with the development environment
+	devenv shell
+
+htmlcov: .coverage
+	coverage html
+
+coverage.xml: .coverage
+	coverage xml
+
+coverage: coverage.xml
+
+.PHONY: test\ all
+test\ all:  ## Test all supported versions
+	make PYTHON=python314 SPHINX=8.2.3 clean devenv-show devenv-test
+	make PYTHON=python314 SPHINX=8.1.3 clean devenv-show devenv-test
+	make PYTHON=python314 SPHINX=8.0.2 clean devenv-show devenv-test
+	make PYTHON=python314 SPHINX=7.4.7 clean devenv-show devenv-test
+	make PYTHON=python313 SPHINX=8.2.3 clean devenv-show devenv-test
+	make PYTHON=python313 SPHINX=8.1.3 clean devenv-show devenv-test
+	make PYTHON=python313 SPHINX=8.0.2 clean devenv-show devenv-test
+	make PYTHON=python313 SPHINX=7.4.7 clean devenv-show devenv-test
+	make PYTHON=python312 SPHINX=8.2.3 clean devenv-show devenv-test
+	make PYTHON=python312 SPHINX=8.1.3 clean devenv-show devenv-test
+	make PYTHON=python312 SPHINX=8.0.2 clean devenv-show devenv-test
+	make PYTHON=python312 SPHINX=7.4.7 clean devenv-show devenv-test
+	make PYTHON=python311 SPHINX=8.2.3 clean devenv-show devenv-test
+	make PYTHON=python311 SPHINX=8.1.3 clean devenv-show devenv-test
+	make PYTHON=python311 SPHINX=8.0.2 clean devenv-show devenv-test
+	make PYTHON=python311 SPHINX=7.4.7 clean devenv-show devenv-test
+	make PYTHON=python310 SPHINX=8.1.3 clean devenv-show devenv-test
+	make PYTHON=python310 SPHINX=8.0.2 clean devenv-show devenv-test
+	make PYTHON=python310 SPHINX=7.4.7 clean devenv-show devenv-test
+
+devenv.local.nix:
+	@echo '{ pkgs, ...}: { languages.python = { interpreter = pkgs.$(PYTHON); dependencies = [ "sphinx$(subst .,,$(SPHINX))" "dev" ]; }; }' > devenv.local.nix
+# /development and contributing

sphinxcontrib_httpexample-2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: sphinxcontrib-httpexample
+Version: 2.0
+Summary: Adds example directive for sphinx-contrib httpdomain
+Project-URL: Repository, https://github.com/collective/sphinxcontrib-httpexample
+Author-email: Asko Soukka <asko.soukka@iki.fi>
+License: GPL-2.0-only
+Keywords: documentation,extension,http,rest,sphinx
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: docutils
+Requires-Dist: importlib-metadata
+Requires-Dist: importlib-resources
+Requires-Dist: sphinx
+Requires-Dist: sphinxcontrib-httpdomain
+Provides-Extra: sphinx747
+Requires-Dist: sphinx==7.4.7; (python_version >= '3.10') and extra == 'sphinx747'
+Provides-Extra: sphinx802
+Requires-Dist: sphinx==8.0.2; (python_version >= '3.10') and extra == 'sphinx802'
+Provides-Extra: sphinx813
+Requires-Dist: babel; extra == 'sphinx813'
+Requires-Dist: sphinx==8.1.3; (python_version >= '3.10') and extra == 'sphinx813'
+Provides-Extra: sphinx823
+Requires-Dist: sphinx==8.2.3; (python_version >= '3.11') and extra == 'sphinx823'
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# sphinxcontrib-httpexample
+
+<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://pypi.org/project/sphinxcontrib-httpexample/">
+<img alt="Documentation" src="https://readthedocs.org/projects/sphinxcontrib-httpexample/badge/?version=latest" href="https://sphinxcontrib-httpexample.readthedocs.io/en/latest/">
+
+sphinxcontrib-httpexample is a Sphinx domain extension for describing RESTful HTTP APIs in detail.
+It enhances [`sphinxcontrib-httpdomain`](https://github.com/sphinx-contrib/httpdomain) with a simple call example directive.
+The directive provided by this extension generates RESTful HTTP API call examples for different HTTP clients from a single HTTP request example.
+
+The audience for this extension are developers and technical writers documenting their RESTful HTTP APIs.
+This extension was originally developed for documenting [`plone.restapi`](https://6.docs.plone.org/plone.restapi/docs/source/index.html).
+
+
+## Features
+
+-   Directive for generating various RESTful HTTP API call examples from a single HTTP request.
+-   Supported HTTP clients:
+
+    -   [curl](https://curl.haxx.se/)
+    -   [wget](https://www.gnu.org/software/wget/)
+    -   [httpie](https://httpie.io/)
+    -   [requests](https://requests.readthedocs.io/en/stable/)
+
+-   Custom builders, such as the [`@plone/client`](https://www.npmjs.com/package/@plone/client) package, an agnostic library that provides easy access to the Plone REST API from a client written in TypeScript.
+    See https://sphinxcontrib-httpexample.readthedocs.io/en/latest/custom.html for examples.
+
+
+## Examples
+
+This extension has been used in documentation for the following projects and probably other similar projects as well.
+
+-   https://6.docs.plone.org/plone.restapi/docs/source/index.html
+-   https://sphinxcontrib-httpexample.readthedocs.io/en/latest/
+-   https://guillotina.readthedocs.io/en/latest/
+
+
+## Documentation
+
+Full documentation for end users can be found in the `docs` folder.
+It's also available online at https://sphinxcontrib-httpexample.readthedocs.io/en/latest/.
+
+
+## Installation
+
+Add `sphinxcontrib-httpexample` and `sphincontrib-httpdomain` to your project requirements.
+
+Then configure your Sphinx configuration file `conf.py` with `sphinxcontrib.httpdomain` and `sphinxcontrib.httpexample` as follows.
+
+```python
+extensions = [
+    "sphinxcontrib.httpdomain",
+    "sphinxcontrib.httpexample",
+]
+```
+
+
+## Contribute
+
+To contribute to `sphinxcontrib-httpexample`, first set up your environment.
+
+
+### Set up development environment
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
+Carefully read the console output for further instruction.
+
+```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.
+
+```shell
+make livehtml
+```
+
+To stop the preview, type `CTRL-C`.
+
+
+### Run tests
+
+```shell
+make test
+```
+
+
+## License
+
+The project is licensed under the GPLv2.