|
| 1 | +# Documentation Community Team Meeting (March 3, 2026) |
| 2 | + |
| 3 | +## Roll call |
| 4 | + |
| 5 | +(Name / `@GitHubUsername` *[/ Discord, if different]*) |
| 6 | + |
| 7 | +* Hugo van Kemenade / `@hugovk` |
| 8 | +* Trey Hunner / `@treyhunner` |
| 9 | +* Ned Batchelder / `@nedbat` |
| 10 | +* Ryan Duve / `@ryan-duve` |
| 11 | +* Maciej Olko / `@m-aciek` |
| 12 | +* Joe Kaufeld / `@itsthejoker` |
| 13 | + |
| 14 | + |
| 15 | +## Reports and celebrations |
| 16 | + |
| 17 | +* We now get Plausible analytics data from the devguide |
| 18 | + (See: [analytics.python.org/devguide.python.org](https://analytics.python.org/devguide.python.org)). |
| 19 | + |
| 20 | +* New blog website at [blog.python.org](https://blog.python.org)! |
| 21 | + Thanks to Jacob Coffee, we no longer need to use Blogger! |
| 22 | + |
| 23 | + |
| 24 | +## Discussion |
| 25 | + |
| 26 | +* [Ryan] Running `man python3` shows documentation with unexpected newlines: |
| 27 | + |
| 28 | + ``` |
| 29 | + -X showrefcount: output the total reference count and number |
| 30 | + of used |
| 31 | + memory blocks when the program finishes or after each |
| 32 | + statement in the |
| 33 | + interactive interpreter. This only works on debug builds |
| 34 | + ``` |
| 35 | + |
| 36 | + The newlines are [not in the source](https://github.com/python/cpython/blob/fdb4b3527f356a84bc00ca32516181016400e567/Misc/python.man#L383), |
| 37 | + but it seems to [appear in a few places](https://github.com/search?q=repo%3Apython%2Fcpython+%22blocks+when+the+program+finishes+or%22&type=code). |
| 38 | + If this is an isolated bug, I think we can simply open an issue for it, but first |
| 39 | + I wanted to discuss whether others have thoughts on generally tracking how |
| 40 | + documentation is presented uniformly across all channels, e.g., PDF vs HTML, etc. |
| 41 | + |
| 42 | + We discussed that this may be due to manpage settings. |
| 43 | + [python/cpython#145649](https://github.com/python/cpython/issues/145649) |
| 44 | + is open as an action item to highlight this. |
| 45 | + |
| 46 | + |
| 47 | +* [Ned] linklint: |
| 48 | + [Pull request](https://github.com/python/cpython/pull/145130), [discuss.python.org thread](https://discuss.python.org/t/should-not-underline-links/106012/28) |
| 49 | + |
| 50 | + The Discourse thread complained about link underlines being distracting in the |
| 51 | + docs. We aren't removing the underlines, but we can remove unnecessary links. |
| 52 | + Linklint started as a linter and fixer to update .rst files, but it works |
| 53 | + better as a Sphinx extension. Now it removes unneeded links from references |
| 54 | + during the build process. This means we don't have to hard-code linking |
| 55 | + decisions in .rst files, and we don't need to make churnful PRs to get rid of links. |
| 56 | + (Note: since the meeting, this has been completed.) |
| 57 | + |
| 58 | + One downside to the Sphinx extension: .rst has a syntax for making a reference |
| 59 | + but preventing the link. We have no syntax for a reference to insist on being |
| 60 | + a link even though the extension thinks it would be excessive. |
| 61 | + |
| 62 | + A possible next step is to remove links for "obvious" references like `int`, |
| 63 | + `float`, `str`, `list` and so on. We did not come to a conclusion about |
| 64 | + whether that would be a good idea or not. |
| 65 | + |
| 66 | +* [Hugo] `import datetime as dt` ([python/cpython#145315](https://github.com/python/cpython/pull/145315)) |
| 67 | + |
| 68 | + A discussion from 2023 suggested renaming `datetime.datetime` to |
| 69 | + `datetime.DateTime` to avoid confusion between the module, and the class |
| 70 | + inside the module. The topic suggested other renamings, deprecations, and aliases, |
| 71 | + which could involve breaking changes or warnings in lots of code. |
| 72 | + |
| 73 | + Hugo commented that he follows [Adam Johnson's recommendation](https://adamj.eu/tech/2019/09/12/how-i-import-pythons-datetime-module/) |
| 74 | + of `import datetime as dt` and then you can unambiguously use |
| 75 | + `dt.datetime`, `dt.time`, and `dt.timezone`. He said he's been using the |
| 76 | + pattern for several years and finds it much better than the alternatives. |
| 77 | + Terry suggested in the thread to use `import datetime as dt` in the docs. |
| 78 | + |
| 79 | + Others in the meeting were generally in favour of the PR: |
| 80 | + it's docs only, doesn't change the stdlib, doesn't introduce warnings. |
| 81 | + People can continue to use whatever pattern they wish in their own code. |
| 82 | + |
| 83 | + Some used `from datetime import datetime, time` but thought |
| 84 | + `import datetime as dt` is better as it avoids the potential confusion, |
| 85 | + and thought it would be better for learners as well. |
| 86 | + |
| 87 | +* [Maciek] PDF builds broken due to SVGs ([python/docs-community#182](https://github.com/python/docs-community/issues/182)) |
| 88 | + * Currently, PDF builds are broken on 3.15 and 3.14 docs. There are several |
| 89 | + options on how we can fix it. It would be worth deciding which approach we |
| 90 | + should take. |
| 91 | + * [Hugo] Not keen on storing PDF graphics in the repository, as binary blobs. |
| 92 | + One idea, which would be quick to implement, is to gate on the PDF builder |
| 93 | + and not show any image, instead have some description if needed. |
| 94 | + |
| 95 | +* Transifex has a higher plan for ~6 months. Thanks to Adam T. and Hugo for |
| 96 | + making it possible! |
| 97 | + * [Hugo] Remember it's a one-year trial. Towards the end of the year, we need |
| 98 | + to evaluate whether we wish to continue with it, and if so write up why. |
0 commit comments