Documentation: Unlock writing in Markdown, using Sphinx/MyST. Add Sphinx extensions "copybutton" and "opengraph".

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,6 +57,11 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_design_elements",
+    "sphinxext.opengraph",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -226,3 +231,57 @@
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
+
+# -- 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/.
+#
+# About text lengths
+#
+# Original documentation says:
+# - ogp_description_length
+#   Configure the amount of characters taken from a page. The default of 200 is probably good
+#   for most people. If something other than a number is used, it defaults back to 200.
+#   -- https://sphinxext-opengraph.readthedocs.io/en/latest/#options
+#
+# Other people say:
+# - og:title 40 chars
+# - og:description has 2 max lengths:
+#   When the link is used in a Post, it's 300 chars. When a link is used in a Comment, it's 110 chars.
+#   So you can either treat it as 110, or, write your Descriptions to 300 but make sure the first 110
+#   is the critical part and still makes sense when it gets cut off.
+#   -- https://stackoverflow.com/questions/8914476/facebook-open-graph-meta-tags-maximum-content-length
+ogp_site_url = "https://responder.kennethreitz.org/"
+ogp_description_length = 300
+ogp_site_name = "Responder Documentation"
+ogp_image = "https://responder.kennethreitz.org/_static/responder.png"
+ogp_image_alt = False
+ogp_use_first_image = False
+ogp_type = "website"
+ogp_enable_meta_description = True
+
+# -- 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}: "
+copybutton_prompt_is_regexp = True

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,7 +123,11 @@ def run(self):
         ],
         "docs": [
             "alabaster<1.1",
+            "myst-parser[linkify]",
             "sphinx>=5,<9",
+            "sphinx-copybutton",
+            "sphinx-design-elements",
+            "sphinxext.opengraph",
         ],
         "graphql": ["graphene"],
         "release": ["build", "twine"],