Replace update-docs-help.py with cog, closes #1598

docs/cli-reference.rst

@@ -26,6 +26,8 @@ This page lists the ``--help`` for every ``datasette`` CLI command.
     cog.out("\n")
     for command in commands:
         title = "datasette " + " ".join(command)
+        ref = "_cli_help_" + ("_".join(command).replace("-", "_"))
+        cog.out(".. {}:\n\n".format(ref))
         cog.out(title + "\n")
         cog.out(("=" * len(title)) + "\n\n")
         cog.out("::\n\n")
@@ -35,6 +37,8 @@ This page lists the ``--help`` for every ``datasette`` CLI command.
         cog.out("\n\n")
 .. ]]]
 
+.. _cli_help___help:
+
 datasette --help
 ================
 
@@ -61,6 +65,8 @@ datasette --help
       uninstall  Uninstall plugins and Python packages from the Datasette...
 
 
+.. _cli_help_serve___help:
+
 datasette serve --help
 ======================
 
@@ -114,6 +120,8 @@ datasette serve --help
       --help                    Show this message and exit.
 
 
+.. _cli_help_serve___help_settings:
+
 datasette serve --help-settings
 ===============================
 
@@ -165,6 +173,8 @@ datasette serve --help-settings
 
 
 
+.. _cli_help_plugins___help:
+
 datasette plugins --help
 ========================
 
@@ -180,6 +190,8 @@ datasette plugins --help
       --help                   Show this message and exit.
 
 
+.. _cli_help_publish___help:
+
 datasette publish --help
 ========================
 
@@ -198,6 +210,8 @@ datasette publish --help
       heroku    Publish databases to Datasette running on Heroku
 
 
+.. _cli_help_publish_cloudrun___help:
+
 datasette publish cloudrun --help
 =================================
 
@@ -242,6 +256,8 @@ datasette publish cloudrun --help
       --help                          Show this message and exit.
 
 
+.. _cli_help_publish_heroku___help:
+
 datasette publish heroku --help
 ===============================
 
@@ -281,6 +297,8 @@ datasette publish heroku --help
       --help                          Show this message and exit.
 
 
+.. _cli_help_package___help:
+
 datasette package --help
 ========================
 
@@ -317,6 +335,8 @@ datasette package --help
       --help                    Show this message and exit.
 
 
+.. _cli_help_inspect___help:
+
 datasette inspect --help
 ========================
 
@@ -335,6 +355,8 @@ datasette inspect --help
       --help                 Show this message and exit.
 
 
+.. _cli_help_install___help:
+
 datasette install --help
 ========================
 
@@ -349,6 +371,8 @@ datasette install --help
       --help         Show this message and exit.
 
 
+.. _cli_help_uninstall___help:
+
 datasette uninstall --help
 ==========================
 

docs/getting_started.rst

@@ -161,11 +161,4 @@ The ``--get`` option can specify the path to a page within Datasette and cause D
 
 The exit code will be 0 if the request succeeds and 1 if the request produced an HTTP status code other than 200 - e.g. a 404 or 500 error. This means you can use ``datasette --get /`` to run tests against a Datasette application in a continuous integration environment such as GitHub Actions.
 
-.. _getting_started_serve_help:
-
-datasette serve --help
-----------------------
-
-Running ``datasette downloads.db`` executes the default ``serve`` sub-command, and is equivalent to running ``datasette serve downloads.db``. The full list of options to that command is shown below.
-
-.. literalinclude:: datasette-serve-help.txt
+Running ``datasette`` without specifying a command runs the default command, ``datasette serve``.  See :ref:`cli_help_serve___help` for the full list of options for that command.

docs/publish.rst

@@ -47,7 +47,7 @@ Once it has finished it will output a URL like this one::
 
 Cloud Run provides a URL on the ``.run.app`` domain, but you can also point your own domain or subdomain at your Cloud Run service - see `mapping custom domains <https://cloud.google.com/run/docs/mapping-custom-domains>`__ in the Cloud Run documentation for details.
 
-.. literalinclude:: datasette-publish-cloudrun-help.txt
+See :ref:`cli_help_publish_cloudrun___help` for the full list of options for this command.
 
 Publishing to Heroku
 --------------------
@@ -64,7 +64,7 @@ This will output some details about the new deployment, including a URL like thi
 
 You can specify a custom app name by passing ``-n my-app-name`` to the publish command. This will also allow you to overwrite an existing app.
 
-.. literalinclude:: datasette-publish-heroku-help.txt
+See :ref:`cli_help_publish_heroku___help` for the full list of options for this command.
 
 .. _publish_vercel:
 
@@ -171,4 +171,4 @@ You can customize the port that is exposed by the container using the ``--port``
 
 A full list of options can be seen by running ``datasette package --help``:
 
-.. literalinclude:: datasette-package-help.txt
+See :ref:`cli_help_package___help` for the full list of options for this command.

tests/test_docs.py

@@ -33,26 +33,6 @@ def test_settings_are_documented(settings_headings, setting):
     assert setting.name in settings_headings
 
 
-@pytest.mark.parametrize(
-    "name,filename",
-    (
-        ("serve", "datasette-serve-help.txt"),
-        ("package", "datasette-package-help.txt"),
-        ("publish heroku", "datasette-publish-heroku-help.txt"),
-        ("publish cloudrun", "datasette-publish-cloudrun-help.txt"),
-    ),
-)
-def test_help_includes(name, filename):
-    expected = (docs_path / filename).read_text()
-    runner = CliRunner()
-    result = runner.invoke(cli, name.split() + ["--help"], terminal_width=88)
-    actual = f"$ datasette {name} --help\n\n{result.output}"
-    # actual has "Usage: cli package [OPTIONS] FILES"
-    # because it doesn't know that cli will be aliased to datasette
-    expected = expected.replace("Usage: datasette", "Usage: cli")
-    assert expected == actual, "Run python update-docs-help.py to fix this"
-
-
 @pytest.fixture(scope="session")
 def plugin_hooks_content():
     return (docs_path / "plugin_hooks.rst").read_text()