diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.md similarity index 63% rename from .github/CONTRIBUTING.rst rename to .github/CONTRIBUTING.md index 504b5135f9..f749d4fe86 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.md @@ -1,14 +1,10 @@ -========================= -Contributing to |project| -========================= +# Contributing to Cheroot -Make sure you read the `README -`_. -Also **ensure you set up pre-commit utility correctly** and -tests pass in GitHub Actions CI/CD workflows. +**Ensure you set up pre-commit utility correctly** and tests pass in +GitHub Actions CI/CD workflows. + +## Submitting Pull Requests -Submitting Pull Requests -^^^^^^^^^^^^^^^^^^^^^^^^ If you're changing the structure of the repository please create an issue first. Don't forget to write appropriate test cases, add them into CI process if applicable and make the GitHub Actions CI/CD build pass. @@ -19,27 +15,25 @@ us able to merge your PR seamlessly. Please fill out the pull request template that GitHub adds to your PR description automatically when you open one -- it covers what kind of change you're making, whether it affects user-facing behavior, and a -checklist reviewers expect to be addressed (tests, a ``changelog`` -entry, etc.). PRs that skip it may be closed without review. +checklist reviewers expect to be addressed (tests, a `changelog` entry, +etc.). PRs that skip it may be closed without review. If you're submitting this PR through an automated or AI-assisted tool that posts directly via the GitHub API, the pull request template isn't shown to you automatically the way it would be through the -GitHub web UI. Fetch ``.github/PULL_REQUEST_TEMPLATE.md`` directly +GitHub web UI. Fetch `.github/PULL_REQUEST_TEMPLATE.md` directly and fill it in yourself. -Submitting bug reports -^^^^^^^^^^^^^^^^^^^^^^ +## Submitting bug reports -Make sure you are on latest changes and that you re-ran this command ``tox`` +Make sure you are on latest changes and that you re-ran this command `tox` after updating your local repository. If you can, please provide more information about your environment such as browser, operating system, python version, and any other related software versions. It is also helpful to post a markdown snippet demonstrating minimum reproducible example of an issue. -Also -^^^^ -See the `contribution guidelines -`_ +## Also + +See the fuller [contribution guidelines](https://cheroot.cherrypy.dev/en/latest/contributing/guidelines/) for more detail, including code style, testing, and the change log process. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c95b28b108..6f6ba6441d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -36,7 +36,7 @@ repos: |contrib |misc )(\.\d+)?(\.rst)? - |README\.rst + |README\.md |\.towncrier-template\.rst\.j2 ) $ diff --git a/dependencies/tox-docs.in b/dependencies/tox-docs.in index a05afe7ee3..e8c8f67261 100644 --- a/dependencies/tox-docs.in +++ b/dependencies/tox-docs.in @@ -6,7 +6,7 @@ jaraco.packaging >= 9 # first version to load meta through PEP 517 interface sphinx-tabs >= 1.1.0 furo -myst-parser[linkify] # Markdown documents support w/ in-text link detector +myst-parser [linkify] >= 5.1.0 # Markdown documents support w/ in-text link detector; >=5.1.0 for the `alert` extension sphinx-issues # Sphinx roles providing support for linking GitHub sphinxcontrib-apidoc >= 0.3.0 sphinxcontrib-towncrier diff --git a/docs/changelog-fragments.d/.gitignore b/docs/changelog-fragments.d/.gitignore index 4db39ea08a..51c7e37535 100644 --- a/docs/changelog-fragments.d/.gitignore +++ b/docs/changelog-fragments.d/.gitignore @@ -1,7 +1,7 @@ * !.gitignore !.towncrier-template.rst.j2 -!README.rst +!README.md !*.bugfix !*.bugfix.rst !*.bugfix.*.rst diff --git a/docs/changelog-fragments.d/842.doc.rst b/docs/changelog-fragments.d/842.doc.rst new file mode 100644 index 0000000000..113ab801cd --- /dev/null +++ b/docs/changelog-fragments.d/842.doc.rst @@ -0,0 +1,7 @@ +Converted the contributing documentation (``.github/CONTRIBUTING.rst``, +``docs/contributing/guidelines.rst`` and +``docs/changelog-fragments.d/README.rst``) to Markdown, fixed a +self-referential link in the "Also" section that pointed the rendered +guidelines page back to itself, and dropped an unhelpful pointer to the +project's root README +-- by :user:`julianz-`. diff --git a/docs/changelog-fragments.d/README.rst b/docs/changelog-fragments.d/README.md similarity index 51% rename from docs/changelog-fragments.d/README.rst rename to docs/changelog-fragments.d/README.md index 8ad074d2b0..74defe212a 100644 --- a/docs/changelog-fragments.d/README.rst +++ b/docs/changelog-fragments.d/README.md @@ -1,12 +1,9 @@ -.. _Adding change notes with your PRs: - -Adding change notes with your PRs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +## Adding change notes with your PRs It is very important to maintain a log for news of how updating to the new version of the software will affect end-users. This is why we enforce collection of the change -fragment files in pull requests as per `Towncrier philosophy`_. +fragment files in pull requests as per [Towncrier philosophy]. The idea is that when somebody makes a change, they must record the bits that would affect end-users only including information @@ -18,13 +15,12 @@ related details generates noise that is not particularly useful to the end-users most of the time. And so such details should be recorded in the Git history rather than a change log. -Alright! So how do I add a news fragment? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +## Alright! So how do I add a news fragment? -*Cheroot* uses `towncrier `_ +*Cheroot* uses [towncrier](https://pypi.org/project/towncrier/) for change log management. To submit a change note about your PR, add a text file into the -``docs/changelog-fragments.d/`` folder. It should contain an +`docs/changelog-fragments.d/` folder. It should contain an explanation of what applying this PR will change in the way end-users interact with the project. One sentence is usually enough but feel free to add as many details as you feel necessary @@ -39,38 +35,37 @@ linking parts of the docs or external sites. However, you do not need to reference the issue or PR numbers here as *towncrier* will automatically add a reference to all of the affected issues when rendering the news file. -If you wish to sign your change, feel free to add ``-- by -:user:`github-username``` at the end (replace ``github-username`` +If you wish to sign your change, feel free to add `` -- by :user:`github-username` `` at the end (replace `github-username` with your own!). Finally, name your file following the convention that Towncrier understands: it should start with the number of an issue or a -PR followed by a dot, then add a patch type, like ``feature``, -``doc``, ``contrib`` etc., and add ``.rst`` as a suffix. If you +PR followed by a dot, then add a patch type, like `feature`, +`doc`, `contrib` etc., and add `.rst` as a suffix. If you need to add more than one fragment, you may add an optional sequence number (delimited with another period) between the type and the suffix. -In general the name will follow ``..rst`` pattern, +In general the name will follow `..rst` pattern, where the categories are: -- ``bugfix``: A bug fix for something we deemed an improper undesired +- `bugfix`: A bug fix for something we deemed an improper undesired behavior that got corrected in the release to match pre-agreed expectations. -- ``feature``: A new behavior, public APIs. That sort of stuff. -- ``deprecation``: A declaration of future API removals and breaking +- `feature`: A new behavior, public APIs. That sort of stuff. +- `deprecation`: A declaration of future API removals and breaking changes in behavior. -- ``breaking``: When something public gets removed in a breaking way. +- `breaking`: When something public gets removed in a breaking way. Could be deprecated in an earlier release. -- ``doc``: Notable updates to the documentation structure or build +- `doc`: Notable updates to the documentation structure or build process. -- ``packaging``: Notes for downstreams about unobvious side effects +- `packaging`: Notes for downstreams about unobvious side effects and tooling. Changes in the test invocation considerations and runtime assumptions. -- ``contrib``: Stuff that affects the contributor experience. e.g. +- `contrib`: Stuff that affects the contributor experience. e.g. Running tests, building the docs, setting up the development environment. -- ``misc``: Changes that are hard to assign to any of the above +- `misc`: Changes that are hard to assign to any of the above categories. A pull request may have more than one of these components, for example @@ -79,38 +74,35 @@ feature, in which case two fragments should be added. It is not necessary to make a separate documentation fragment for documentation changes accompanying the relevant code changes. -Examples for adding change log entries to your Pull Requests -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -File :file:`docs/changelog-fragments.d/77.doc.rst`: +## Examples for adding change log entries to your Pull Requests -.. code-block:: rst +File `docs/changelog-fragments.d/77.doc.rst`: - Fixed a WSGI documentation example to support Python 3 - -- by :user:`jaymcgrath`. +```rst +Fixed a WSGI documentation example to support Python 3 +-- by :user:`jaymcgrath`. +``` -File :file:`docs/changelog-fragments.d/384.feature.rst` (could be symlinked -to :file:`docs/changelog-fragments.d/384.doc.rst` so it shows up in several -change log sections, and to :file:`docs/changelog-fragments.d/385.feature.rst` -and :file:`docs/changelog-fragments.d/406.feature.rst` referencing several +File `docs/changelog-fragments.d/384.feature.rst` (could be symlinked +to `docs/changelog-fragments.d/384.doc.rst` so it shows up in several +change log sections, and to `docs/changelog-fragments.d/385.feature.rst` +and `docs/changelog-fragments.d/406.feature.rst` referencing several pull requests at once): -.. code-block:: rst - - Exposed type stubs with annotations for public API -- by :user:`kasium`. - -File :file:`docs/changelog-fragments.d/359.bugfix.rst`: - -.. code-block:: rst +```rst +Exposed type stubs with annotations for public API -- by :user:`kasium`. +``` - Fixed a regression from :pr:`199` that made the worker threads exit on - invalid connection attempts and could make the whole server unresponsive - once there was no workers left -- by :user:`cameronbrunner`. +File `docs/changelog-fragments.d/359.bugfix.rst`: -.. tip:: +```rst +Fixed a regression from :pr:`199` that made the worker threads exit on +invalid connection attempts and could make the whole server unresponsive +once there was no workers left -- by :user:`cameronbrunner`. +``` - See :file:`towncrier.toml` for all available categories - (``tool.towncrier.type``). +> [!TIP] +> See `towncrier.toml` for all available categories +> (`tool.towncrier.type`). -.. _Towncrier philosophy: - https://towncrier.readthedocs.io/en/stable/#philosophy +[Towncrier philosophy]: https://towncrier.rtfd.io/en/stable/#philosophy diff --git a/docs/conf.py b/docs/conf.py index 1d526cae44..586ca78684 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,6 +44,14 @@ 'spelling_stub_ext', # auto-loads `sphinxcontrib.spelling` if installed ] +myst_enable_extensions = [ + # Enables GitHub's `> [!TIP]`-style alerts to render as Sphinx + # admonitions too. Needed for files like README.md and + # CONTRIBUTING.md, which GitHub also renders directly as plain + # GFM -- this way the same syntax works correctly in both places. + 'alert', +] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md new file mode 100644 index 0000000000..0fac949c87 --- /dev/null +++ b/docs/contributing/guidelines.md @@ -0,0 +1,138 @@ +```{include} ../../.github/CONTRIBUTING.md +:end-before: "## Also" +``` + +## First-time setup + +- You need to install [Python](https://www.python.org/) 3 which is required for building docs. + For example, Python 3.11. + + Then, [create and activate a virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments). + And install [tox](https://tox.readthedocs.io/en/latest/). + +- [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + +- [Configure git](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup): + + 1. Please, identify yourself: + + ```console + $ git config --global user.name "firstname lastname" + $ git config --global user.email yourname@example.com + ``` + + Use the address bound to your GitHub account so that the commits would be linked to your profile. + + 2. Choose an editor for Git: + + ```console + $ git config --global core.editor vim + ``` + +- Create and log in to a [GitHub](http://github.com) account + +- [Fork](https://help.github.com/articles/fork-a-repo/) Cheroot to your GitHub account by clicking the Fork button + +- [Clone](https://help.github.com/articles/cloning-a-repository/) your fork locally: + + ```console + $ git clone https://github.com/{username}/cheroot + $ cd cheroot + ``` + + Also, you can [clone](https://help.github.com/articles/cloning-a-repository/) fork using [ssh](https://help.github.com/articles/connecting-to-github-with-ssh/): + + ```console + $ git clone git@github.com:{username}/cheroot.git + $ cd cheroot + ``` + +- To create a new [branch](https://www.atlassian.com/git/tutorials/using-branches) and switch to it: + + ```console + $ git checkout -b patch/some_fix + ``` + +## Write your code + +- Please, use [PEP 8](https://pep8.org/) + +### Once you finished coding, you are recommended to do the following steps: + +- Run tests with [tox](https://tox.readthedocs.io/en/latest/) + +Run one test with Python3.11: + +```console +$ tox -e py311 -- cheroot/test/test_name.py +``` + +**`tox`** — Run all tests using the Python version where `python` command +currently points to which is specified in `tox` settings: + +```ini +envlist = python +minversion = 3.21.0 +``` + +Run linters and all tests against several Python interpreters: + +```console +$ tox -e pre-commit,py310,py37 # etc. +``` + +- Run the [pre-commit](https://github.com/pre-commit/pre-commit) linting suite: + + ```console + $ tox -e pre-commit + ``` + +- [git add](https://git-scm.com/docs/git-add) your files + +- [Write good](https://chris.beams.io/posts/git-commit/) [commit messages](https://git-scm.com/docs/git-commit) when checking in your changes to Git + +- [Push](https://git-scm.com/docs/git-push) and [create a pull request](https://help.github.com/articles/creating-a-pull-request/) + +## Building the docs + +To build the docs from a checked out source, run: + +```console +$ tox -e build-docs +``` + +Open the documentation: + +`````{tabs} +````{tab} GNU/Linux +```console +$ xdg-open build/html/index.html +``` +```` + +````{tab} macOS +```console +$ open build/html/index.html +``` +```` + +````{tab} Windows +Please, open `build/html/index.html` in your browser. +```` +````` + +Also, one can serve docs using a built-in static files server. +This is preferable because of possible CSRF issues. + +```console +$ python3 -m http.server --directory build/html/ 8000 +``` + +After that, you can open [http://localhost:8000/](http://localhost:8000/) in your browser. + +Read more about [Sphinx](https://www.sphinx-doc.org). + +(adding change notes with your prs)= + +```{include} ../changelog-fragments.d/README.md +``` diff --git a/docs/contributing/guidelines.rst b/docs/contributing/guidelines.rst deleted file mode 100644 index 4a03e0837f..0000000000 --- a/docs/contributing/guidelines.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. include:: ../../.github/CONTRIBUTING.rst - - -First-time setup -~~~~~~~~~~~~~~~~ - -- You need to install `Python`_ 3 which is required for building docs. - For example, Python 3.11. - - Then, `create and activate a virtual environment`_. - And install `tox`_. - -- `Install git`_ - -- `Configure git`_: - -1. Please, identify yourself:: - - $ git config --global user.name "firstname lastname" - $ git config --global user.email yourname@example.com - -* Use the address bound to your GitHub account so that the commits would be linked to your profile. - -2. Choose an editor for Git:: - - $ git config --global core.editor vim - -- Create and log in to a `GitHub`_ account - -- `Fork`_ Cheroot to your GitHub account by clicking the Fork button - -- `Clone`_ your fork locally:: - - $ git clone https://github.com/{username}/cheroot - $ cd cheroot - -* Also, you can `clone`_ fork using `ssh`_:: - - $ git clone git@github.com:{username}/cheroot.git - $ cd cheroot - -- To create a new `branch`_ and switch to it:: - - $ git checkout -b patch/some_fix - -.. _create and activate a virtual environment: https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments -.. _Python: https://www.python.org/ -.. _Install git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -.. _Configure git: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup -.. _GitHub: http://github.com -.. _Fork: https://help.github.com/articles/fork-a-repo/ -.. _Clone: https://help.github.com/articles/cloning-a-repository/ -.. _ssh: https://help.github.com/articles/connecting-to-github-with-ssh/ -.. _branch: https://www.atlassian.com/git/tutorials/using-branches - -Write your code -~~~~~~~~~~~~~~~ - -- Please, use `PEP 8`_ - -.. _PEP 8: https://pep8.org/ - -Once you finished coding, you are recommended to do the following steps: -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -- Run tests with `tox`_ - -Run one test with Python3.11:: - - $ tox -e py311 -- cheroot/test/test_name.py - -**``tox``** — Run all tests using the Python version where `python` command -currently points to which is specified in ``tox`` settings:: - - envlist = python - minversion = 3.21.0 - -Run linters and all tests against several Python interpreters:: - - $ tox -e pre-commit,py310,py37 # etc. - -- Run the `pre-commit`_ linting suite:: - - $ tox -e pre-commit - -- `git add`_ your files - -- `Write good`_ `commit messages`_ when checking in your changes to Git - -- `Push`_ and `create a pull request`_ - -.. _tox: https://tox.readthedocs.io/en/latest/ -.. _pre-commit: https://github.com/pre-commit/pre-commit -.. _git add: https://git-scm.com/docs/git-add -.. _Write good: https://chris.beams.io/posts/git-commit/ -.. _commit messages: https://git-scm.com/docs/git-commit -.. _Push: https://git-scm.com/docs/git-push -.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/ - -Building the docs -~~~~~~~~~~~~~~~~~ - -To build the docs from a checked out source, run:: - - $ tox -e build-docs - -Open the documentation: - -.. tabs:: - - .. tab:: GNU/Linux - - :: - - $ xdg-open build/html/index.html - - .. tab:: macOS - - :: - - $ open build/html/index.html - - .. tab:: Windows - - Please, open ``build/html/index.html`` in your browser. - -Also, one can serve docs using a built-in static files server. -This is preferable because of possible CSRF issues.:: - - $ python3 -m http.server --directory build/html/ 8000 - -After that, you can open `http://localhost:8000/ `_ in your browser. - -Read more about `Sphinx`_. - -.. _Sphinx: https://www.sphinx-doc.org - -.. include:: ../changelog-fragments.d/README.rst