Documentation: Unlock writing in Markdown, using Sphinx/MyST

README.md

@@ -88,4 +88,4 @@ Requests.
 
 ## Development
 
-See [Development Sandbox](DEVELOP.md).
+See [Development Sandbox](https://responder.kennethreitz.org/sandbox.html).

docs/source/conf.py

@@ -57,7 +57,9 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "myst_parser",
     "sphinx_copybutton",
+    "sphinx_design",
     "sphinxext.opengraph",
 ]
 
@@ -229,7 +231,26 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-# Configure OpenGraph extension
+# -- Options for MyST --------------------------------------------------------
+
+myst_heading_anchors = 3
+myst_enable_extensions = [
+    "attrs_block",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+myst_substitutions = {}
+
+# -- Options for OpenGraph ---------------------------------------------------
 #
 # When making changes, check them using the RTD PR preview URL on https://www.opengraph.xyz/.
 #
@@ -257,7 +278,8 @@
 ogp_type = "website"
 ogp_enable_meta_description = True
 
-# Configure Sphinx-copybutton
+# -- Options for sphinx-copybutton -------------------------------------------
+
 copybutton_remove_prompts = True
 copybutton_line_continuation_character = "\\"
 copybutton_prompt_text = r">>> |\.\.\. |\$ |sh\$ |PS> |cr> |mysql> |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "

docs/source/index.rst

@@ -117,7 +117,14 @@ Or use standard pip where ``uv`` is not available.
 
     pip install --upgrade 'responder'
 
-Responder supports **Python 3.6+**.
+Responder supports **Python 3.6+**. If you are looking at installing Responder
+for hacking on it, please refer to the :ref:`sandbox` documentation.
+
+.. toctree::
+   :hidden:
+
+   sandbox
+
 
 
 The Basic Idea

DEVELOP.md → docs/source/sandbox.md

@@ -1,16 +1,23 @@
+(sandbox)=
 # Development Sandbox
 
+## Setup
 Set up a development sandbox.
 
-Acquire sources and install project in editable mode.
+Acquire sources and create virtualenv.
 ```shell
 git clone https://github.com/kennethreitz/responder
 cd responder
 python3 -m venv .venv
 source .venv/bin/activate
-pip install --editable '.[graphql,develop,docs,release,test]'
 ```
 
+Install project in editable mode.
+```shell
+pip install --editable '.[full,develop,docs,release,test]'
+```
+
+## Operations
 Invoke linter and software tests.
 ```shell
 poe check

setup.py

@@ -123,8 +123,10 @@ def run(self):
         ],
         "docs": [
             "alabaster<1.1",
+            "myst-parser[linkify]",
             "sphinx>=5,<9",
             "sphinx-copybutton",
+            "sphinx-design-elements",
             "sphinxext.opengraph",
         ],
         "graphql": ["graphene"],