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/requirements.txt

@@ -1,8 +1,11 @@
 furo
 jinja2<3.2
 markupsafe<4
+myst-parser[linkify]
 readme-renderer<45
 sphinx>=5,<9
-sphinxcontrib-websupport<2.1
 sphinx-copybutton
-sphinxext.opengraph
+sphinx-design-elements
+sphinxcontrib-mermaid
+sphinxcontrib-websupport<2.1
+sphinxext-opengraph

docs/source/conf.py

@@ -57,7 +57,10 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "myst_parser",
     "sphinx_copybutton",
+    "sphinx_design",
+    "sphinxcontrib.mermaid",
     "sphinxext.opengraph",
 ]
 
@@ -234,7 +237,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/.
 #
@@ -262,7 +284,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`` on systems 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
+
 
 Design
 ------

DEVELOP.md → docs/source/sandbox.md

@@ -1,16 +1,22 @@
+(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,release,test]'
+```
+Install project in editable mode.
+```shell
+pip install --editable '.[full,develop,test]'
 ```
 
+## Operations
 Invoke linter and software tests.
 ```shell
 poe check