Documentation Community Team Meeting (December 3, 2024)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Petr Viktorin /
@encukouDaniele
Erlend /
@erlend-aaslandTrey
Bartosz /
@bswckHugo van Kemenade /
@hugovkNed /
@nedbatStan Ulbrych /
@StanFromIrelandRyan Duve /
ryan-duveBlaise Pabon /
controlpl4n3
Discussion¶
[Erlend]: Undocumented
calendarAPIs; what to do? (recently brought up by Pieter Eendebak.) According to Serhiy, several APIs are deliberately undocumented:But first than documenting these particular method or two, we should decide whether they should be documented at all.
See past issues with the
calendarmodule. There may be requests for undocumented methods, and some of them may even be rejected already. I think this has already been discussed.I could not find previous discussions nor issues regarding this. IMO, we should either document public API, or at least add an explanatory comment in the source code that some APIs are deliberately undocumented. See also:
Discussion:
[Petr] backwards compat (PEP 387) says things without underscore are supported, even if not documented
[Petr] a possibility is also to deprecate the APIs, or document them as deprecated
[Erlend] list from Adam of undocumented APIs: python/cpython#108202 (comment)
there was a short discussion that it was not immediately obvious if these APIs were meant to be public or not
[Erlend] will try to dig up previous discussions; maybe there are some in the python-dev archive; will post a summary on the gh-108202 issue in a few days
[Carol] [from Nov] API navigation or tables on long pages: https://discuss.python.org/t/summary-tables-as-an-api-overview/68474
python/cpython#125810 -> docs.python.org/3/library/math.html [merged!]
python/cpython#126342 -> cpython-previews–126342.org.readthedocs.build/en/126342/library/pathlib.html#summary
Petr to figure out the Sphinx side of how to solve this, then ping Trey to polish the CSS
Translation dashboard