diff --git a/cmake_modules/trike/README.md b/cmake_modules/trike/README.md
deleted file mode 100644
index ec371e2..0000000
--- a/cmake_modules/trike/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-Simple doc comments for C++
-===========================
-
-A Sphinx extension which scans C++ sources and headers
-for `///` comments. [libclang](https://libclang.readthedocs.io)
-is used to associate these with declarations. These can then be
-referenced using the `.. trike-put::` directive.
-
-For example, given the following C++ and rst sources in your project:
-
-```c++
-/// Frobnicates the :cpp:var:`whatsit` register.
-void frobnicate();
-```
-
-```rst
-.. trike-put:: cpp:function frobnicate
-```
-
-... a [`cpp:function`](https://www.sphinx-doc.org/en/master/usage/domains/cpp.html#directive-cpp-function)
-directive will be introduced with content drawn from the `///`
-
-The content of `///` is interpreted as ReStructuredText, so
-they can be as expressive as the rest of your documentation. Of particular
-note for those who have used other apidoc systems: cross references from
-`///` comments to labels defined in `*.rst` (or other `///`a) will just work.
diff --git a/cmake_modules/trike/README.rst b/cmake_modules/trike/README.rst
new file mode 100644
index 0000000..e74b28d
--- /dev/null
+++ b/cmake_modules/trike/README.rst
@@ -0,0 +1,37 @@
+Simple doc comments for C++
+===========================
+
+A Sphinx extension which scans C++ sources and headers
+for `///` comments. [libclang](https://libclang.readthedocs.io)
+is used to associate these with declarations. These can then be
+referenced using `.. trike-put::` and other directives.
+
+For example, given the following C++ and rst sources in your project:
+
+``frob.cxx``
+    .. code-block:: c++
+
+      /// Frobnicates the :cpp:var:`whatsit` register.
+      ///
+      /// :return: false if no frobnication was necessary
+      bool frobnicate();
+
+``index.rst``
+    .. code-block:: rst
+
+      .. trike-function:: void frobnicate()
+
+The ``trike-function`` directive above will render equivalently to
+a [`cpp:function`](https://www.sphinx-doc.org/en/master/usage/domains/cpp.html#directive-cpp-function)
+directive with content drawn from the `///`.
+
+.. cpp:function:: void frobnicate()
+
+  Frobnicates the :cpp:var:`whatsit` register.
+
+  :return: false if no frobnication was necessary
+
+The content of ``///`` is interpreted as ReStructuredText, so
+they can be as expressive as the rest of your documentation. Of particular
+note for those who have used other apidoc systems: cross references from
+``///`` comments to labels defined in `*.rst` (or other ``///``) will just work.
diff --git a/cmake_modules/trike/pyproject.toml b/cmake_modules/trike/pyproject.toml
index 5720a25..bc627bf 100644
--- a/cmake_modules/trike/pyproject.toml
+++ b/cmake_modules/trike/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "trike"
 description = "Simple doc comments for C++"
-readme = "README.md"
+readme = "README.rst"
 version = "0.0.1"
 dependencies = [
   "libclang",