From 23970b7d1ce4d0a7de91feb1c9ad79df6b094d8e Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@panodata.org>
Date: Sun, 27 Oct 2024 17:47:35 +0100
Subject: [PATCH] Documentation: Unlock writing in Markdown, using Sphinx/MyST

---
 README.md                            |  2 +-
 docs/source/conf.py                  | 26 ++++++++++++++++++++++++--
 docs/source/index.rst                |  9 ++++++++-
 DEVELOP.md => docs/source/sandbox.md | 11 +++++++++--
 setup.py                             |  2 ++
 5 files changed, 44 insertions(+), 6 deletions(-)
 rename DEVELOP.md => docs/source/sandbox.md (64%)

diff --git a/README.md b/README.md
index 2745010..4851e98 100644
--- a/README.md
+++ b/README.md
@@ -88,4 +88,4 @@ Requests.
 
 ## Development
 
-See [Development Sandbox](DEVELOP.md).
+See [Development Sandbox](https://responder.kennethreitz.org/sandbox.html).
diff --git a/docs/source/conf.py b/docs/source/conf.py
index e61e75c..1693125 100644
--- a/docs/source/conf.py
+++ b/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}: "
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a4a2256..83cc6ef 100644
--- a/docs/source/index.rst
+++ b/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
diff --git a/DEVELOP.md b/docs/source/sandbox.md
similarity index 64%
rename from DEVELOP.md
rename to docs/source/sandbox.md
index d99938a..88f4ada 100644
--- a/DEVELOP.md
+++ b/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
diff --git a/setup.py b/setup.py
index d9df305..7ffe9fe 100644
--- a/setup.py
+++ b/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"],