Convert README.md from reST to MD.

Author: stevepiercy

README.md

@@ -1,108 +1,95 @@
-sphinxcontrib-httpexample
-=========================
+# sphinxcontrib-httpexample
 
-.. image:: https://github.com/collective/sphinxcontrib-httpexample/actions/workflows/build.yml/badge.svg?branch=master
-   :target: https://github.com/collective/sphinxcontrib-httpexample/actions
+<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://badge.fury.io/py/sphinxcontrib-httpexample">
+<img alt="Documentation" src="https://readthedocs.org/projects/sphinxcontrib-httpexample/badge/?version=latest" href="http://sphinxcontrib-httpexample.readthedocs.io/en/latest">
 
-.. image:: https://coveralls.io/repos/github/collective/sphinxcontrib-httpexample/badge.svg?branch=master
-   :target: https://coveralls.io/github/collective/sphinxcontrib-httpexample?branch=master
+sphinxcontrib-httpexample enhances [`sphinxcontrib-httpdomain`](https://pythonhosted.org/sphinxcontrib-httpdomain/), a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.
 
-.. image:: https://badge.fury.io/py/sphinxcontrib-httpexample.svg
-   :target: https://badge.fury.io/py/sphinxcontrib-httpexample
+The audience for this extension are developers and technical writes documenting their RESTful HTTP APIs. This extension has originally been developed for documenting [`plone.restapi`](https://6.docs.plone.org/plone.restapi/docs/source/index.html).
 
-.. image:: https://readthedocs.org/projects/sphinxcontrib-httpexample/badge/?version=latest
-   :target: http://sphinxcontrib-httpexample.readthedocs.io/en/latest
 
-sphinxcontrib-httpexample enhances `sphinxcontrib-httpdomain`_, a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.
+## Features
 
-The audience for this extension are developers and technical writes documenting their RESTful HTTP APIs. This extension has originally been developed for documenting `plone.restapi`_.
+-   Directive for generating various RESTful HTTP API call examples from single HTTP request.
+-   Supported tools:
 
-.. _sphinxcontrib-httpdomain: https://pythonhosted.org/sphinxcontrib-httpdomain/
-.. _plone.restapi: http://plonerestapi.readthedocs.org/
+    -   [curl](https://curl.haxx.se/)
+    -   [wget](https://www.gnu.org/software/wget/)
+    -   [httpie](https://httpie.org/)
+    -   [python-requests](http://docs.python-requests.org/)
 
 
-Features
---------
+## Examples
 
-* Directive for generating various RESTful HTTP API call examples from single HTTP request.
+This extension has been used at least in the following documentations:
 
-* Supported tools:
+-   https://6.docs.plone.org/plone.restapi/docs/source/index.html
+-   https://sphinxcontrib-httpexample.readthedocs.org/en/latest/
+-   https://guillotina.readthedocs.io/en/latest/
 
-  - curl_
-  - wget_
-  - httpie_
-  - python-requests_
 
-.. _curl: https://curl.haxx.se/
-.. _wget: https://www.gnu.org/software/wget/
-.. _httpie: https://httpie.org/
-.. _python-requests: http://docs.python-requests.org/
+## Documentation
 
+Full documentation for end users can be found in the "docs" folder. It is also available online at http://sphinxcontrib-httpexample.readthedocs.org/
 
-Examples
---------
 
-This extension has been used at least in the following documentations:
+## Installation
 
-* http://plonerestapi.readthedocs.org/
-* http://sphinxcontrib-httpexample.readthedocs.org/
-* https://guillotina.readthedocs.io/en/latest/
+Add `sphinxcontrib-httpexample` and `sphincontrib-httpdomain` into your project requirements.
 
+Then configure your Sphinx configuration file `conf.py` with `sphinxcontrib.httpdomain` and `sphinxcontrib.httpexample` as follows.
 
-Documentation
--------------
+```python
+extensions = [
+    "sphinxcontrib.httpdomain",
+    "sphinxcontrib.httpexample",
+]
+```
 
-Full documentation for end users can be found in the "docs" folder. It is also available online at http://sphinxcontrib-httpexample.readthedocs.org/
 
+## Contribute
 
-Installation
-------------
+To contribute to `sphinxcontrib-httpexample`, first set up your environment.
 
-Add sphinxcontrib-httpexample into requirements of your product documentation and into the configuration file of your Sphinx documentation next to sphincontrib-httpdomain as follows:
 
-..  code:: python
+### Set up development environment
 
-    extensions = ['sphinxcontrib.httpdomain', 'sphinxcontrib.httpexample']
+Install [uv](https://6.docs.plone.org/glossary.html#term-uv).
+Carefully read the console output for further instructions, and follow them, if needed.
 
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
 
-## Contribute
+Initialize a Python virtual environment.
 
 ```shell
 uv venv
+```
+
+Install `sphinxcontrib-httpexample`.
+
+```shell
 uv sync
-make watch
 ```
 
-Yields
-
-```console
-$ make watch
-PYTHONPATH=/Users/stevepiercy/projects/sphinxcontrib-httpexample/docs sphinx-autobuild -b html docs docs/html
-[sphinx-autobuild] > sphinx-build -b html /Users/stevepiercy/projects/sphinxcontrib-httpexample/docs /Users/stevepiercy/projects/sphinxcontrib-httpexample/docs/html
-Running Sphinx v4.5.0
-
-Configuration error:
-There is a programmable error in your configuration file:
-
-Traceback (most recent call last):
-  File "/Users/stevepiercy/.pyenv/versions/3.10.13/lib/python3.10/site-packages/sphinx/config.py", line 332, in eval_config_file
-    exec(code, namespace)
-  File "/Users/stevepiercy/projects/sphinxcontrib-httpexample/docs/conf.py", line 86, in <module>
-    dist = metadata.distribution("sphinxcontrib-httpexample")
-  File "/Users/stevepiercy/.pyenv/versions/3.10.13/lib/python3.10/importlib/metadata/__init__.py", line 969, in distribution
-    return Distribution.from_name(distribution_name)
-  File "/Users/stevepiercy/.pyenv/versions/3.10.13/lib/python3.10/importlib/metadata/__init__.py", line 548, in from_name
-    raise PackageNotFoundError(name)
-importlib.metadata.PackageNotFoundError: No package metadata was found for sphinxcontrib-httpexample
-
-Command exited with exit code: 2
-The server will continue serving the build folder, but the contents being served are no longer in sync with the documentation sources. Please fix the cause of the error above or press Ctrl+C to stop the server.
-[I 251202 22:42:04 server:335] Serving on http://127.0.0.1:8000
-[I 251202 22:42:04 handlers:62] Start watching changes
+### 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
+
+make te
 
-License
--------
+## License
 
 The project is licensed under the GPLv2.