{"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1031126801", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1031126801, "node_id": "IC_kwDOBm6k_c49db8R", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-07T06:43:31Z", "updated_at": "2022-02-07T06:43:31Z", "author_association": "OWNER", "body": "Here's the new test: https://github.com/simonw/datasette/blob/03305ea183b1534bc4cef3a721fe5f3700273b84/tests/test_docs.py#L91-L104", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1031126547", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1031126547, "node_id": "IC_kwDOBm6k_c49db4T", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-07T06:42:58Z", "updated_at": "2022-02-07T06:42:58Z", "author_association": "OWNER", "body": "That fixed it: https://docs.datasette.io/en/latest/internals.html#parse-metadata-content\r\n\r\n\"image\"\r\n", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1031125347", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1031125347, "node_id": "IC_kwDOBm6k_c49dblj", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-07T06:40:16Z", "updated_at": "2022-02-07T06:40:16Z", "author_association": "OWNER", "body": "Read The Docs error:\r\n\r\n> Problem in your project's configuration. Invalid \"python.version\": .readthedocs.yaml: Invalid configuration option: python.version. Make sure the key name is correct.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1031123719", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1031123719, "node_id": "IC_kwDOBm6k_c49dbMH", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-07T06:36:32Z", "updated_at": "2022-02-07T06:36:32Z", "author_association": "OWNER", "body": "https://github.com/simonw/sqlite-utils/blob/main/.readthedocs.yaml looks like this (it works correctly):\r\n\r\n```yaml\r\nversion: 2\r\n\r\nsphinx:\r\n configuration: docs/conf.py\r\n\r\npython:\r\n version: \"3.8\"\r\n install:\r\n - method: pip\r\n path: .\r\n extra_requirements:\r\n - docs\r\n```\r\nCompare to the current Datasette one here: https://github.com/simonw/datasette/blob/d9b508ffaa91f9f1840b366f5d282712d445f16b/.readthedocs.yaml#L1-L13\r\n\r\nLooks like I need this bit:\r\n```python\r\npython:\r\n version: \"3.8\"\r\n install:\r\n - method: pip\r\n path: .\r\n extra_requirements:\r\n - docs\r\n```", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1031122800", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1031122800, "node_id": "IC_kwDOBm6k_c49da9w", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-07T06:34:21Z", "updated_at": "2022-02-07T06:34:21Z", "author_association": "OWNER", "body": "New section is here: https://docs.datasette.io/en/latest/internals.html#the-datasette-utils-module\r\n\r\nBut it's not correctly displaying the new autodoc stuff:\r\n\r\n\"image\"\r\n", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1031108559", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1031108559, "node_id": "IC_kwDOBm6k_c49dXfP", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-07T06:11:27Z", "updated_at": "2022-02-07T06:11:27Z", "author_association": "OWNER", "body": "I'm going with `@documented` as the decorator for functions that should be documented.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-1030762279", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 1030762279, "node_id": "IC_kwDOBm6k_c49cC8n", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-02-06T06:38:08Z", "updated_at": "2022-02-06T06:41:37Z", "author_association": "OWNER", "body": "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\r\n\r\nThis would encourage me to add really good docstrings.\r\n\r\n```\r\n.. _python_api_gis_find_spatialite:\r\n\r\nFinding SpatiaLite\r\n------------------\r\n\r\n.. autofunction:: sqlite_utils.utils.find_spatialite\r\n```", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-969616626", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 969616626, "node_id": "IC_kwDOBm6k_c45yyzy", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-11-16T01:29:13Z", "updated_at": "2021-11-16T01:29:13Z", "author_association": "OWNER", "body": "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", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-755159583", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 755159583, "node_id": "MDEyOklzc3VlQ29tbWVudDc1NTE1OTU4Mw==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-01-06T08:28:20Z", "updated_at": "2021-01-06T08:28:20Z", "author_association": "OWNER", "body": "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.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-754957378", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 754957378, "node_id": "MDEyOklzc3VlQ29tbWVudDc1NDk1NzM3OA==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-01-05T23:12:03Z", "updated_at": "2021-01-05T23:12:03Z", "author_association": "OWNER", "body": "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.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-754952146", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 754952146, "node_id": "MDEyOklzc3VlQ29tbWVudDc1NDk1MjE0Ng==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-01-05T22:57:26Z", "updated_at": "2021-01-05T22:57:26Z", "author_association": "OWNER", "body": "Known public APIs might be worth adding type annotations to as well.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-754952040", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 754952040, "node_id": "MDEyOklzc3VlQ29tbWVudDc1NDk1MjA0MA==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-01-05T22:57:09Z", "updated_at": "2021-01-05T22:57:09Z", "author_association": "OWNER", "body": "It might be neater to move all of the non-public functions into a separate module - `datasette.utils.internal` perhaps.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null} {"html_url": "https://github.com/simonw/datasette/issues/1176#issuecomment-754951786", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1176", "id": 754951786, "node_id": "MDEyOklzc3VlQ29tbWVudDc1NDk1MTc4Ng==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-01-05T22:56:27Z", "updated_at": "2021-01-05T22:56:43Z", "author_association": "OWNER", "body": "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.\r\n```python\r\n@documented\r\ndef escape_css_string(s):\r\n return _css_re.sub(\r\n lambda m: \"\\\\\" + (f\"{ord(m.group()):X}\".zfill(6)),\r\n s.replace(\"\\r\\n\", \"\\n\"),\r\n )\r\n```\r\nOr maybe `@public`?", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 779691739, "label": "Policy on documenting \"public\" datasette.utils functions"}, "performed_via_github_app": null}