Convert contributing docs to Markdown

.github/CONTRIBUTING.rst → .github/CONTRIBUTING.md

@@ -1,14 +1,10 @@
-=========================
-Contributing to |project|
-=========================
+# Contributing to Cheroot
 
-Make sure you read the `README
-<https://github.com/cherrypy/cheroot/blob/main/README.rst>`_.
-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
-<https://cheroot.cherrypy.dev/en/latest/contributing/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.

.pre-commit-config.yaml

@@ -36,7 +36,7 @@ repos:
             |contrib
             |misc
           )(\.\d+)?(\.rst)?
-          |README\.rst
+          |README\.md
           |\.towncrier-template\.rst\.j2
         )
       $

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

docs/changelog-fragments.d/.gitignore

@@ -1,7 +1,7 @@
 *
 !.gitignore
 !.towncrier-template.rst.j2
-!README.rst
+!README.md
 !*.bugfix
 !*.bugfix.rst
 !*.bugfix.*.rst

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-`.

docs/changelog-fragments.d/README.rst → 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 <https://pypi.org/project/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 ``<pr_number>.<category>.rst`` pattern,
+In general the name will follow `<pr_number>.<category>.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

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']
 

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
+```