issue_comments

Here's the new test: https://github.com/simonw/datasette/blob/03305ea183b1534bc4cef3a721fe5f3700273b84/tests/test_docs.py#L91-L104

That fixed it: https://docs.datasette.io/en/latest/internals.html#parse-metadata-content

Read The Docs error:

Problem in your project's configuration. Invalid "python.version": .readthedocs.yaml: Invalid configuration option: python.version. Make sure the key name is correct.

https://github.com/simonw/sqlite-utils/blob/main/.readthedocs.yaml looks like this (it works correctly):

```yaml version: 2

sphinx: configuration: docs/conf.py

python: version: "3.8" install: - method: pip path: . extra_requirements: - docs ``` Compare to the current Datasette one here: https://github.com/simonw/datasette/blob/d9b508ffaa91f9f1840b366f5d282712d445f16b/.readthedocs.yaml#L1-L13

Looks like I need this bit: python python: version: "3.8" install: - method: pip path: . extra_requirements: - docs

New section is here: https://docs.datasette.io/en/latest/internals.html#the-datasette-utils-module

But it's not correctly displaying the new autodoc stuff:

I'm going with @documented as the decorator for functions that should be documented.

Might do this using Sphinx auto-generated function and class documentation hooks, as seen here in sqlite-utils: https://sqlite-utils.datasette.io/en/stable/python-api.html#spatialite-helpers

This would encourage me to add really good docstrings.

``` .. _python_api_gis_find_spatialite:

Finding SpatiaLite

.. autofunction:: sqlite_utils.utils.find_spatialite ```

I'm inclined to create a Sphinx reference documentation page for this, as I did for sqlite-utils here: https://sqlite-utils.datasette.io/en/stable/reference.html

I used from datasette.utils import path_with_format in https://github.com/simonw/datasette-export-notebook/blob/0.1/datasette_export_notebook/init.py just now.

This needs to be done for Datasette 1.0. At the very least I need to ensure it's clear that datasette.utils is not part of the public API unless explicitly marked as such.

Known public APIs might be worth adding type annotations to as well.

It might be neater to move all of the non-public functions into a separate module - datasette.utils.internal perhaps.

Idea: introduce a @documented decorator which marks specific functions as part of the public, documented API. The unit tests can then confirm that anything with that decorator is both documented and tested. python @documented def escape_css_string(s): return _css_re.sub( lambda m: "\\" + (f"{ord(m.group()):X}".zfill(6)), s.replace("\r\n", "\n"), ) Or maybe @public?