|
| 1 | +Thank you for contributing! |
| 2 | +=========================== |
| 3 | + |
| 4 | +Thank you for considering a contribution to Sphinx reStructuredText |
| 5 | +builder/writer, and for reading this document. |
| 6 | + |
| 7 | +Use issues for bug reports, feature requests, or any sort of feedback |
| 8 | +that you may have. |
| 9 | + |
| 10 | +If you are able to spend the time to create a pull request, that is |
| 11 | +most appreciated. |
| 12 | + |
| 13 | + |
| 14 | +Testing your code |
| 15 | +================= |
| 16 | + |
| 17 | +* Run `pytest`_ to run all tests using your default Python version and |
| 18 | + Sphinx version. |
| 19 | + |
| 20 | +* Run `pytest -k testName` to only run the test called testName. |
| 21 | + |
| 22 | +* For testing, Sphinx is run for each test in the `tests/datasets` |
| 23 | + directory, and the output is written to the `output` directory. |
| 24 | + The result is then compared to the expected output in |
| 25 | + `tests/expected`. |
| 26 | + |
| 27 | +* Rather than a byte-by-byte comparison, `output` and `tests/expected` |
| 28 | + are compared after reading the file with docutils (which contains a |
| 29 | + basic reStructuredText parser), to allow for slight variations in |
| 30 | + layout. |
| 31 | + |
| 32 | +* If a test fails, the XML version of the parsed documents is written |
| 33 | + to the `output` directory. `test-file.expected.xml` for |
| 34 | + `test-file.rst` in `tests/expected`, and `test-file.output.xml` for |
| 35 | + `test-file.rst` in `output`. |
| 36 | + |
| 37 | +* Optionally run `pytest -v -r A -W d` for a very verbose output, |
| 38 | + including stdout and stderr for all tests (note that some tests like |
| 39 | + nonexistent-target.rst are expected to give a warning), and including |
| 40 | + all Python warnings. |
| 41 | + |
| 42 | +* To test with multiple Python version and Sphinx versions, run `tox`_. |
| 43 | + |
| 44 | +* Run `tox -e python3.9-sphinx3.4` to run tox with a specific Python |
| 45 | + and Sphinx version. |
| 46 | + |
| 47 | +* Each commit to master, and each pull request to the master branch is |
| 48 | + tested with a few different tests. See the actions tab for the |
| 49 | + results of each run, or click on the checkmark (✔ or ✘) listed with |
| 50 | + each commit. |
| 51 | + |
| 52 | +.. _pytest: https://www.pytest.org/ |
| 53 | +.. _tox: https://tox.readthedocs.io/ |
| 54 | + |
| 55 | + |
| 56 | +Supported versions |
| 57 | +================== |
| 58 | + |
| 59 | +* See `.github/workflows/tests.yml` for a list of which version are |
| 60 | + tested for by GitHub after each pull request. |
| 61 | + |
| 62 | +* See `tox.ini` for a list of which version are tested for by `tox`. |
| 63 | + These two files should be kept in sync. |
| 64 | + |
| 65 | +* As a rule of thumb, this project supports all Sphinx versions |
| 66 | + starting from the one that came with the previous stable Debian |
| 67 | + distribution (`oldstable/sphinx-doc`_) till the most recent version. |
| 68 | + It supports all Python versions starting with the one that came with |
| 69 | + the previous stable Debian distribution (`oldstable/python3`_). |
| 70 | + |
| 71 | +* Python 2 is no longer supported, and no test is run for it. |
| 72 | + We will consider small pull requests to add Python 2.7 support, if |
| 73 | + you really want to spend this effort. |
| 74 | + |
| 75 | +.. _`oldstable/sphinx-doc`: https://packages.debian.org/oldstable/sphinx-doc |
| 76 | +.. _`oldstable/python`: https://packages.debian.org/oldstable/python3 |
| 77 | + |
| 78 | + |
| 79 | +Publishing versions |
| 80 | +=================== |
| 81 | + |
| 82 | +The code is available on the Python package index at |
| 83 | +https://pypi.org/project/sphinxcontrib-restbuilder/. |
| 84 | + |
| 85 | +This section is only relevant for administrators. |
| 86 | + |
| 87 | +Creating a release |
| 88 | +------------------ |
| 89 | + |
| 90 | +Change the following files:: |
| 91 | + |
| 92 | + CHANGES.rst |
| 93 | + CONTRIBUTORS.txt (Add new contributors, if any) |
| 94 | + setup.py (Change version constant) |
| 95 | + |
| 96 | +Commit the changes, add a tag, and upload the changes:: |
| 97 | + |
| 98 | + git add CHANGES.rst CONTRIBUTORS.txt setup.py |
| 99 | + git commit -m "Bump version number to x.y.z" |
| 100 | + git tag -a version-x.y.z HEAD |
| 101 | + git push --tags |
| 102 | + |
| 103 | +Publish a release at GitHub |
| 104 | +--------------------------- |
| 105 | + |
| 106 | +* Go to https://github.com/sphinx-contrib/restbuilder/releases |
| 107 | +* Click the "Draft a new release" button |
| 108 | +* Select the tag, and add a Release title (e.g. Sphinx Restbuilder x.y) |
| 109 | + and release notes. I usually only list the most important changes, |
| 110 | + with optional link to CHANGES.rst for more details. |
| 111 | + |
| 112 | +Publish a release at PyPI |
| 113 | +------------------------- |
| 114 | + |
| 115 | +Follow the process described at https://packaging.python.org/tutorials/distributing-packages/. |
| 116 | + |
| 117 | +Install requirements:: |
| 118 | + |
| 119 | + pip install --upgrade pip |
| 120 | + pip install setuptools wheel twine |
| 121 | + |
| 122 | +Create both a source (.tar.gz) and wheel (.whl) distribution:: |
| 123 | + |
| 124 | + python setup.py sdist |
| 125 | + python setup.py bdist_wheel --universal |
| 126 | + |
| 127 | +Upload all that was created to PyPI:: |
| 128 | + |
| 129 | + ls dist/ |
| 130 | + twine upload dist/* |
0 commit comments