-
-
Notifications
You must be signed in to change notification settings - Fork 657
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Policy on documenting "public" datasette.utils functions #1176
Comments
Idea: introduce a @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 |
It might be neater to move all of the non-public functions into a separate module - |
Known public APIs might be worth adding type annotations to as well. |
This needs to be done for Datasette 1.0. At the very least I need to ensure it's clear that |
I used |
I'm inclined to create a Sphinx reference documentation page for this, as I did for |
Might do this using Sphinx auto-generated function and class documentation hooks, as seen here in This would encourage me to add really good docstrings.
|
I'm going with |
New mechanism for marking datasette.utils functions that should be covered by the documentation, then testing that they have indeed been documented. Also enabled sphinx.ext.autodoc which can now be used to embed the documented versions of those functions. Refs #1176
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: |
https://github.com/simonw/sqlite-utils/blob/main/.readthedocs.yaml looks like this (it works correctly): 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: Lines 1 to 13 in d9b508f
Looks like I need this bit: python:
version: "3.8"
install:
- method: pip
path: .
extra_requirements:
- docs |
Read The Docs error:
|
Here's the new test: Lines 91 to 104 in 03305ea
|
https://github.com/simonw/datasette-css-properties starts like this:
escape_css_string
andto_css_class
are not documented, which means relying on them is risky since there's no promise that they won't change.Would be good to figure out a policy on this, and maybe promote some of them to "documented" status.
The text was updated successfully, but these errors were encountered: