1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
# Contribute to httpdomain
- Report issues in the [issue tracker](https://github.com/sphinx-contrib/httpdomain/issues).
- Comment on and resolve issues.
- Submit pull requests from your fork of the httpdomain repository.
- Extend the [documentation](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/).
- Sponsor development of httpdomain through [GitHub Sponsors](https://github.com/sponsors/stevepiercy).
## Prerequisites
- uv
- GNU Make
### uv
Install uv using the [standalone installer method](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer) for your system.
### GNU Make
GNU Make comes installed on most Linux distributions.
On macOS, you must first [install Xcode](https://developer.apple.com/xcode/resources/), then install its command line tools.
On Windows, it is strongly recommended to [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install), which will include `make`.
Finally, it is a good idea to update your system's version of `make`, because some distributions, especially macOS, have an outdated version.
Use your favorite search engine or trusted online resource for how to update `make`.
## Install httpdomain for development
Begin by cloning the httpdomain repository from GitHub.
```shell
git clone https://github.com/sphinx-contrib/httpdomain.git
```
Change your working directory to the cloned repository.
```shell
cd httpdomain
```
Then install a supported Python version for development, create a Python virtual environment, install requirements for development, install [tox](https://tox.wiki/en/stable/) and the [tox-uv](https://github.com/tox-dev/tox-uv) plugin for running tests, and install httpdomain in development mode with a single command.
```shell
make dev
```
## Make commands
For a list of available Make commands, run the following command.
```shell
make help
```
The most common commands are listed below.
Rebuild Sphinx documentation on changes, with live-reload in the browser.
```shell
make livehtml
```
Delete the documentation build directory.
```shell
make clean
```
Delete the documentation build directory and delete and initialize the Python virtual environment.
```shell
make init
```
## Build and test
httpdomain uses tox to both build the documentation and run tests.
To build the documentation and run tests across all supported Python versions, using the following command.
```shell
tox r
```
To run tests for a specific Python version, use the following command, replacing `py314` with the desired version number.
```shell
tox r -e py314
```
> [!NOTE]
> `py314` is the only tox environment that also runs the link checker.
## Pull request requirements
Before submitting your pull request, ensure you have met the following requirements.
1. Add a change log entry to `CHANGELOG.rst`.
1. Add a test which proves your fix and passes.
1. Run all tests to ensure your changes don't break any existing functionality.
1. Add or edit documentation, both as docstrings and narrative documentation, as necessary.
|
