{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627480353", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627480353, "node_id": "IC_kwDOBm6k_c5hAWEh", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T20:09:48Z", "updated_at": "2023-07-08T20:09:48Z", "author_association": "OWNER", "body": "https://docs.datasette.io/en/latest/writing_plugins.html#writing-plugins-that-accept-configuration is fixed now.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627478910", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627478910, "node_id": "IC_kwDOBm6k_c5hAVt-", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T20:01:19Z", "updated_at": "2023-07-08T20:01:19Z", "author_association": "OWNER", "body": "Some examples:\r\n\r\n-  https://docs.datasette.io/en/latest/sql_queries.html#canned-queries\r\n- https://docs.datasette.io/en/latest/sql_queries.html#canned-query-parameters\r\n- https://docs.datasette.io/en/latest/authentication.html#access-to-an-instance\r\n- https://docs.datasette.io/en/latest/facets.html#facets-in-metadata\r\n- https://docs.datasette.io/en/latest/full_text_search.html#configuring-full-text-search-for-a-table-or-view\r\n- https://docs.datasette.io/en/latest/metadata.html\r\n- https://docs.datasette.io/en/latest/custom_templates.html#custom-css-and-javascript\r\n- https://docs.datasette.io/en/latest/plugins.html#plugin-configuration\r\n\r\nI need to fix this section: https://docs.datasette.io/en/latest/writing_plugins.html#writing-plugins-that-accept-configuration", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627455892", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627455892, "node_id": "IC_kwDOBm6k_c5hAQGU", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T18:39:19Z", "updated_at": "2023-07-08T18:39:19Z", "author_association": "OWNER", "body": "```\r\nERROR: Could not find a version that satisfies the requirement Sphinx==6.1.3; extra == \"docs\" (from datasette[docs,test]) (from versions: 0.1.61611, 0.1.61798, 0.1.61843, 0.1.61945, 0.1.61950, 0.2, 0.3, 0.4, 0.4.1, 0.4.2, 0.4.3, 0.5, 0.5.1, 0.5.2b1, 0.5.2, 0.6b1, 0.6, 0.6.1, 0.6.2, 0.6.3, 0.6.4, 0.6.5, 0.6.6, 0.6.7, 1.0b1, 1.0b2, 1.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.0.7, 1.0.8, 1.1, 1.1.1, 1.1.2, 1.1.3, 1.2b1, 1.2b2, 1.2b3, 1.2, 1.2.1, 1.2.2, 1.2.3, 1.3b1, 1.3b2, 1.3b3, 1.3, 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6, 1.4a1, 1.4b1, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.4.4, 1.4.5, 1.4.6, 1.4.7, 1.4.8, 1.4.9, 1.5a1, 1.5a2, 1.5b1, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.5.4, 1.5.5, 1.5.6, 1.6b1, 1.6b2, 1.6b3, 1.6.1, 1.6.2, 1.6.3, 1.6.4, 1.6.5, 1.6.6, 1.6.7, 1.7.0b1, 1.7.0b2, 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.7.4, 1.7.5, 1.7.6, 1.7.7, 1.7.8, 1.7.9, 1.8.0b1, 1.8.0, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.8.5, 1.8.6, 2.0.0b1, 2.0.0b2, 2.0.0, 2.0.1, 2.1.0, 2.1.1, 2.1.2, 2.2.0, 2.2.1, 2.2.2, 2.3.0, 2.3.1, 2.4.0, 2.4.1, 2.4.2, 2.4.3, 2.4.4, 2.4.5, 3.0.0b1, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0, 3.2.1, 3.3.0, 3.3.1, 3.4.0, 3.4.1, 3.4.2, 3.4.3, 3.5.0, 3.5.1, 3.5.2, 3.5.3, 3.5.4, 4.0.0b1, 4.0.0b2, 4.0.0, 4.0.1, 4.0.2, 4.0.3, 4.1.0, 4.1.1, 4.1.2, 4.2.0, 4.3.0, 4.3.1, 4.3.2, 4.4.0, 4.5.0, 5.0.0b1, 5.0.0, 5.0.1, 5.0.2, 5.1.0, 5.1.1, 5.2.0, 5.2.0.post0, 5.2.1, 5.2.2, 5.2.3, 5.3.0)\r\nERROR: No matching distribution found for Sphinx==6.1.3; extra == \"docs\"\r\n```\r\nI'm going to drop Python 3.7.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627451646", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627451646, "node_id": "IC_kwDOBm6k_c5hAPD-", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T18:21:24Z", "updated_at": "2023-07-08T18:21:24Z", "author_association": "OWNER", "body": "This one was tricky:\r\n\r\n<img width=\"764\" alt=\"image\" src=\"https://github.com/simonw/datasette/assets/9599/0fe2886b-4e07-4539-a254-4c47f02c3f65\">\r\n\r\nI wanted complete control over the YAML example here, so I could ensure it used multi-line strings correctly.\r\n\r\nI ended up changing my cog helper function to this:\r\n\r\n```python\r\nimport json\r\nimport textwrap\r\nfrom yaml import safe_dump\r\nfrom ruamel.yaml import round_trip_load\r\n\r\n\r\ndef metadata_example(cog, data=None, yaml=None):\r\n    assert data or yaml, \"Must provide data= or yaml=\"\r\n    assert not (data and yaml), \"Cannot use data= and yaml=\"\r\n    output_yaml = None\r\n    if yaml:\r\n        # dedent it first\r\n        yaml = textwrap.dedent(yaml).strip()\r\n        # round_trip_load to preserve key order:\r\n        data = round_trip_load(yaml)\r\n        output_yaml = yaml\r\n    else:\r\n        output_yaml = safe_dump(data, sort_keys=False)\r\n    cog.out(\"\\n.. tab:: YAML\\n\\n\")\r\n    cog.out(\"    .. code-block:: yaml\\n\\n\")\r\n    cog.out(textwrap.indent(output_yaml, \"        \"))\r\n    cog.out(\"\\n\\n.. tab:: JSON\\n\\n\")\r\n    cog.out(\"    .. code-block:: json\\n\\n\")\r\n    cog.out(textwrap.indent(json.dumps(data, indent=2), \"        \"))\r\n    cog.out(\"\\n\")\r\n```\r\nThis allows me to call it ith YAML in some places:\r\n```\r\n.. [[[cog\r\n    metadata_example(cog, yaml=\"\"\"\r\n    databases:\r\n      fixtures:\r\n        queries:\r\n          neighborhood_search:\r\n            fragment: fragment-goes-here\r\n            hide_sql: true\r\n            sql: |-\r\n              select neighborhood, facet_cities.name, state\r\n              from facetable join facet_cities on facetable.city_id = facet_cities.id\r\n              where neighborhood like '%' || :text || '%' order by neighborhood;\r\n    \"\"\")\r\n.. ]]]\r\n```\r\nI had to introduce https://pypi.org/project/ruamel.yaml/ as a dependency here in order to load YAML from disk while maintaining key order.\r\n\r\nI'm still using `safe_dump(data, sort_keys=False)` from PyYAML as I couldn't get the result I wanted for outputting YAML from an input of JSON using PyYAML.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627450852", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627450852, "node_id": "IC_kwDOBm6k_c5hAO3k", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T18:17:35Z", "updated_at": "2023-07-08T18:17:35Z", "author_association": "OWNER", "body": "I figured out a workaround:\r\n```python\r\nextensions = [\r\n    \"sphinx.ext.extlinks\",\r\n    \"sphinx.ext.autodoc\",\r\n    \"sphinx_copybutton\",\r\n]\r\nif not os.environ.get(\"DISABLE_SPHINX_INLINE_TABS\"):\r\n    extensions += [\"sphinx_inline_tabs\"]\r\n```\r\nThat way I can run `sphinx-build -b xml . _build` successfully if I set that environment variable.\r\n\r\nI get some noisy warnings, but it runs OK. And the resulting `docs.db` file has rows like this, which I think are fine:\r\n\r\n<img width=\"1533\" alt=\"image\" src=\"https://github.com/simonw/datasette/assets/9599/0a289f53-2c6c-43e9-bda1-d4380383a02f\">\r\n", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627448542", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627448542, "node_id": "IC_kwDOBm6k_c5hAOTe", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T18:05:44Z", "updated_at": "2023-07-08T18:05:44Z", "author_association": "OWNER", "body": "Running with `-P` opens a debugger when it hits the error:\r\n```bash\r\nsphinx-build -P -b xml . _build\r\n```\r\n```\r\n(Pdb) list\r\n2023 \t\r\n2024 \t        Raise an exception unless overridden.\r\n2025 \t        \"\"\"\r\n2026 \t        if (self.document.settings.strict_visitor\r\n2027 \t            or node.__class__.__name__ not in self.optional):\r\n2028 ->\t            raise NotImplementedError(\r\n2029 \t                '%s visiting unknown node type: %s'\r\n2030 \t                % (self.__class__, node.__class__.__name__))\r\n2031 \t\r\n2032 \t    def unknown_departure(self, node):\r\n2033 \t        \"\"\"\r\n(Pdb) self.optional\r\n('meta',)\r\n(Pdb) node.__class__.__name__\r\n'TabContainer'\r\n(Pdb) self.document.settings.strict_visitor\r\n(Pdb) type(self.document.settings.strict_visitor)\r\n<class 'NoneType'>\r\n```\r\nSo if I can get `TabContainer` into that `self.optional` list I'll have fixed this problem.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627448180", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627448180, "node_id": "IC_kwDOBm6k_c5hAON0", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T18:03:31Z", "updated_at": "2023-07-08T18:03:31Z", "author_association": "OWNER", "body": "Relevant code: https://github.com/docutils/docutils/blob/3b53ded52bc439d8068b6ecb20ea0a761247e479/docutils/docutils/nodes.py#L2021-L2031\r\n\r\n```python\r\n    def unknown_visit(self, node):\r\n        \"\"\"\r\n        Called when entering unknown `Node` types.\r\n\r\n        Raise an exception unless overridden.\r\n        \"\"\"\r\n        if (self.document.settings.strict_visitor\r\n            or node.__class__.__name__ not in self.optional):\r\n            raise NotImplementedError(\r\n                '%s visiting unknown node type: %s'\r\n                % (self.__class__, node.__class__.__name__))\r\n```", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627447750", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627447750, "node_id": "IC_kwDOBm6k_c5hAOHG", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T18:00:56Z", "updated_at": "2023-07-08T18:00:56Z", "author_association": "OWNER", "body": "Actually no it's in `sphinx-build`:\r\n```\r\n% sphinx-build -b xml . _build\r\nRunning Sphinx v6.1.3\r\nbuilding [mo]: targets for 0 po files that are out of date\r\nwriting output... \r\nbuilding [xml]: targets for 28 source files that are out of date\r\nupdating environment: [new config] 28 added, 0 changed, 0 removed\r\nreading sources... [100%] writing_plugins                                                                                                                          \r\nlooking for now-outdated files... none found\r\npickling environment... done\r\nchecking consistency... done\r\npreparing documents... done\r\nwriting output... [  3%] authentication                                                                                                                            \r\nException occurred:\r\n  File \"/Users/simon/.local/share/virtualenvs/datasette-AWNrQs95/lib/python3.10/site-packages/docutils/nodes.py\", line 2028, in unknown_visit\r\n    raise NotImplementedError(\r\nNotImplementedError: <class 'docutils.writers.docutils_xml.XMLTranslator'> visiting unknown node type: TabContainer\r\nThe full traceback has been saved in /var/folders/x6/31xf1vxj0nn9mxqq8z0mmcfw0000gn/T/sphinx-err-1wkxmkji.log, if you want to report the issue to the developers.\r\nPlease also report this if it was a user error, so that a better error message can be provided next time.\r\nA bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!\r\n```", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627447478", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627447478, "node_id": "IC_kwDOBm6k_c5hAOC2", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T17:59:25Z", "updated_at": "2023-07-08T17:59:25Z", "author_association": "OWNER", "body": "Hit a problem:\r\n```\r\nException occurred:\r\n  File \"/opt/hostedtoolcache/Python/3.9.17/x64/lib/python3.9/site-packages/docutils/nodes.py\", line 2028, in unknown_visit\r\n    raise NotImplementedError(\r\nNotImplementedError: <class 'docutils.writers.docutils_xml.XMLTranslator'> visiting unknown node type: TabContainer\r\nThe full traceback has been saved in /tmp/sphinx-err-tfujyw1h.log, if you want to report the issue to the developers.\r\nPlease also report this if it was a user error, so that a better error message can be provided next time.\r\nA bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!\r\n```\r\nThat's happening here: https://github.com/simonw/datasette/blob/0183e1a72d4d93b1d9a9363f4d47fcc0b5d5849c/.github/workflows/deploy-latest.yml#L42-L48\r\n\r\nMy https://github.com/simonw/sphinx-to-sqlite tool can't handle the new `TabContainer` elements introduced by `sphinx-inline-tabs`.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627396658", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627396658, "node_id": "IC_kwDOBm6k_c5hABoy", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T16:40:07Z", "updated_at": "2023-07-08T16:40:07Z", "author_association": "OWNER", "body": "https://docs.datasette.io/en/latest/metadata.html\r\n\r\n![inline-tabs](https://github.com/simonw/datasette/assets/9599/975bdff5-74ac-451e-92c3-a7dd05d4b862)\r\n", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627396450", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627396450, "node_id": "IC_kwDOBm6k_c5hABli", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T16:38:58Z", "updated_at": "2023-07-08T16:38:58Z", "author_association": "OWNER", "body": "I'm using `cog` and this utility function to generate the YAML/JSON tabs:\r\n\r\nhttps://github.com/simonw/datasette/blob/3b336d8071fb5707bd006de1d614f701d20246a3/docs/metadata_doc.py#L1-L13\r\n\r\nExample usage:\r\n\r\nhttps://github.com/simonw/datasette/blob/3b336d8071fb5707bd006de1d614f701d20246a3/docs/metadata.rst?plain=1#L17-L53", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1627395947", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1627395947, "node_id": "IC_kwDOBm6k_c5hABdr", "user": {"value": 9599, "label": "simonw"}, "created_at": "2023-07-08T16:35:45Z", "updated_at": "2023-07-08T16:35:45Z", "author_association": "OWNER", "body": "I was inspired to finally address this after seeing `sphinx-inline-tabs` at work in https://webcolors.readthedocs.io/en/latest/install.html", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1133267290", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1133267290, "node_id": "IC_kwDOBm6k_c5DjEla", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-05-20T19:44:05Z", "updated_at": "2022-05-20T19:50:58Z", "author_association": "OWNER", "body": "Undocumented Sphinx feature: you can add extra classes to a code example like this:\r\n\r\n```\r\n.. code-block:: json\r\n   :class: metadata-json\r\n\r\n    {\r\n        \"databases\": {\r\n            \"russian-ads\": {\r\n                \"tables\": {\r\n                    \"display_ads\": {\r\n                        \"fts_table\": \"ads_fts\",\r\n                        \"fts_pk\": \"id\",\r\n                        \"searchmode\": \"raw\"\r\n                    }\r\n                }\r\n            }\r\n        }\r\n    }\r\n```\r\nhttps://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block doesn't mention this.\r\n\r\nFiled an issue about the lack of documentation here:\r\n- https://github.com/sphinx-doc/sphinx/issues/10461", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-1133222848", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 1133222848, "node_id": "IC_kwDOBm6k_c5Di5vA", "user": {"value": 9599, "label": "simonw"}, "created_at": "2022-05-20T19:07:10Z", "updated_at": "2022-05-20T19:07:10Z", "author_association": "OWNER", "body": "I could use https://github.com/pradyunsg/sphinx-inline-tabs for this - recommended by https://pradyunsg.me/furo/recommendations/", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805109341", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805109341, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTEwOTM0MQ==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T17:55:48Z", "updated_at": "2021-03-23T18:41:57Z", "author_association": "OWNER", "body": "Beginnings of a UI element for switching between them:\r\n```html\r\n<div style=\"border: 1px solid rgb(225, 228, 229);\r\n  background-color: rgb(238, 255, 204);\r\n  padding: 0.3em;\r\n  position: relative;\r\n  top: 3px;\r\n  font-family: courier;\">\r\n<a href=\"#\" style=\"display: inline-block; padding-left: 0px; padding-right: 2em;\">JSON</a>\r\n<a href=\"#\" style=\"display: inline-block;\">YAML</a>\r\n</div>\r\n```\r\n<img width=\"646\" alt=\"Metadata_\u2014_Datasette_documentation\" src=\"https://user-images.githubusercontent.com/9599/112194637-51f92500-8bc6-11eb-9662-3faa7ef37538.png\">\r\n\r\nThat `<pre>` has a padding of 12px, so using 12px padding on the tab links should get them to line up better.", "reactions": "{\"total_count\": 1, \"+1\": 1, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805047117", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805047117, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTA0NzExNw==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T16:30:15Z", "updated_at": "2021-03-23T16:46:06Z", "author_association": "OWNER", "body": "https://cdnjs.cloudflare.com/ajax/libs/js-yaml/4.0.0/js-yaml.min.js is only 12.5KB zipped, 38KB total - so that's not a bad option.\r\n\r\nhttps://github.com/nodeca/js-yaml", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805056806", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805056806, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTA1NjgwNg==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T16:43:38Z", "updated_at": "2021-03-23T16:43:38Z", "author_association": "OWNER", "body": "I used this code to get that:\r\n```javascript\r\nvar jsonVersion = JSON.stringify(window.jsyaml.load(document.querySelector('.highlight-yaml').textContent), null, 4);\r\ndiv.querySelector('.highlight pre').innerText = jsonVersion;\r\ndiv.querySelector('.highlight pre').style.whiteSpace = 'pre-wrap'\r\n```", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805055291", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805055291, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTA1NTI5MQ==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T16:41:31Z", "updated_at": "2021-03-23T16:41:31Z", "author_association": "OWNER", "body": "One downside of doing this conversion in JavaScript: it's much harder to get the same JSON syntax highlighting as that provided by Sphinx:\r\n\r\n<img width=\"655\" alt=\"Metadata_\u2014_Datasette_documentation\" src=\"https://user-images.githubusercontent.com/9599/112183909-ef9b2700-8bbb-11eb-882b-aeb387c29e61.png\">\r\n", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805050163", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805050163, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTA1MDE2Mw==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T16:34:35Z", "updated_at": "2021-03-23T16:35:32Z", "author_association": "OWNER", "body": "https://docs.datasette.io/en/stable/metadata.html has this example:\r\n```yaml\r\ntitle: Demonstrating Metadata from YAML\r\ndescription_html: |-\r\n  <p>This description includes a long HTML string</p>\r\n  <ul>\r\n    <li>YAML is better for embedding HTML strings than JSON!</li>\r\n  </ul>\r\nlicense: ODbL\r\nlicense_url: https://opendatacommons.org/licenses/odbl/\r\ndatabases:\r\n  fixtures:\r\n    tables:\r\n      no_primary_key:\r\n        hidden: true\r\n    queries:\r\n      neighborhood_search:\r\n        sql: |-\r\n          select neighborhood, facet_cities.name, state\r\n          from facetable join facet_cities on facetable.city_id = facet_cities.id\r\n          where neighborhood like '%' || :text || '%' order by neighborhood;\r\n        title: Search neighborhoods\r\n        description_html: |-\r\n          <p>This demonstrates <em>basic</em> LIKE search\r\n```\r\n\r\nI ran this in the browser dev tools:\r\n```javascript\r\nvar s = document.createElement('script')\r\ns.src = 'https://cdnjs.cloudflare.com/ajax/libs/js-yaml/4.0.0/js-yaml.min.js'\r\ndocument.head.appendChild(s)\r\nvar yamlExample = document.querySelector('.highlight-yaml').textContent);\r\nconsole.log(JSON.stringify(window.jsyaml.load(yamlExample), null, 4))\r\n```\r\nAnd got:\r\n```json\r\n{\r\n    \"title\": \"Demonstrating Metadata from YAML\",\r\n    \"description_html\": \"<p>This description includes a long HTML string</p>\\n<ul>\\n  <li>YAML is better for embedding HTML strings than JSON!</li>\\n</ul>\",\r\n    \"license\": \"ODbL\",\r\n    \"license_url\": \"https://opendatacommons.org/licenses/odbl/\",\r\n    \"databases\": {\r\n        \"fixtures\": {\r\n            \"tables\": {\r\n                \"no_primary_key\": {\r\n                    \"hidden\": true\r\n                }\r\n            },\r\n            \"queries\": {\r\n                \"neighborhood_search\": {\r\n                    \"sql\": \"select neighborhood, facet_cities.name, state\\nfrom facetable join facet_cities on facetable.city_id = facet_cities.id\\nwhere neighborhood like '%' || :text || '%' order by neighborhood;\",\r\n                    \"title\": \"Search neighborhoods\",\r\n                    \"description_html\": \"<p>This demonstrates <em>basic</em> LIKE search\"\r\n                }\r\n            }\r\n        }\r\n    }\r\n}\r\n```", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805042880", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805042880, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTA0Mjg4MA==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T16:24:32Z", "updated_at": "2021-03-23T16:24:32Z", "author_association": "OWNER", "body": "... actually I think I would do that conversion in Python. The client-side YAML parsers all look a little bit heavy to me in terms of additional page weight.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-805041522", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 805041522, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNTA0MTUyMg==", "user": {"value": 9599, "label": "simonw"}, "created_at": "2021-03-23T16:22:46Z", "updated_at": "2021-03-23T16:22:46Z", "author_association": "OWNER", "body": "That's a good idea. I could do that with JavaScript - loading YAML and converting it to JSON in JavaScript shouldn't be hard, and it's better than JSON-to-YAML because there's only one correct JSON representation of a YAML file whereas you can represent a JSON document in YAML in a bunch of different ways.", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}
{"html_url": "https://github.com/simonw/datasette/issues/1153#issuecomment-804640440", "issue_url": "https://api.github.com/repos/simonw/datasette/issues/1153", "id": 804640440, "node_id": "MDEyOklzc3VlQ29tbWVudDgwNDY0MDQ0MA==", "user": {"value": 192568, "label": "mroswell"}, "created_at": "2021-03-23T05:58:20Z", "updated_at": "2021-03-23T05:58:20Z", "author_association": "CONTRIBUTOR", "body": "Could there be a little widget that offers conversion from one to the other? ", "reactions": "{\"total_count\": 0, \"+1\": 0, \"-1\": 0, \"laugh\": 0, \"hooray\": 0, \"confused\": 0, \"heart\": 0, \"rocket\": 0, \"eyes\": 0}", "issue": {"value": 771202454, "label": "Use YAML examples in documentation by default, not JSON"}, "performed_via_github_app": null}