Enable MyST Markdown docs, port events.rst, refs #2565

Justfile

@@ -29,7 +29,7 @@ export DATASETTE_SECRET := "not_a_secret"
 
 # Serve live docs on localhost:8000
 @docs: cog blacken-docs
-  cd docs && uv run make livehtml
+  uv sync --extra docs && cd docs && uv run make livehtml
 
 # Apply Black
 @black:

docs/conf.py

@@ -36,12 +36,19 @@ extensions = [
     "sphinx.ext.extlinks",
     "sphinx.ext.autodoc",
     "sphinx_copybutton",
+    "myst_parser",
+    "sphinx_markdown_builder",
 ]
 if not os.environ.get("DISABLE_SPHINX_INLINE_TABS"):
     extensions += ["sphinx_inline_tabs"]
 
 autodoc_member_order = "bysource"
 
+myst_enable_extensions = ["colon_fence"]
+
+markdown_http_base = "https://docs.datasette.io/en/stable"
+markdown_uri_doc_suffix = ".html"
+
 extlinks = {
     "issue": ("https://github.com/simonw/datasette/issues/%s", "#%s"),
 }
@@ -53,7 +60,10 @@ templates_path = ["_templates"]
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
 # The master toctree document.
 master_doc = "index"

docs/events.md

@@ -1,14 +1,14 @@
-.. _events:
+(events)=
-
+# Events
-Events
-======
 
 Datasette includes a mechanism for tracking events that occur while the software is running. This is primarily intended to be used by plugins, which can both trigger events and listen for events.
 
 The core Datasette application triggers events when certain things happen. This page describes those events.
 
-Plugins can listen for events using the :ref:`plugin_hook_track_event` plugin hook, which will be called with instances of the following classes - or additional classes :ref:`registered by other plugins <plugin_hook_register_events>`.
+Plugins can listen for events using the {ref}`plugin_hook_track_event` plugin hook, which will be called with instances of the following classes - or additional classes {ref}`registered by other plugins <plugin_hook_register_events>`.
 
+```{eval-rst}
 .. automodule:: datasette.events
     :members:
     :exclude-members: Event
+```

pyproject.toml

@@ -64,6 +64,8 @@ docs = [
     "blacken-docs",
     "sphinx-copybutton",
     "sphinx-inline-tabs",
+    "myst-parser",
+    "sphinx-markdown-builder",
     "ruamel.yaml",
 ]
 test = [