Details
-
Type:
RFC
-
Status: Proposed
-
Resolution: Unresolved
-
Component/s: DM
-
Labels:
Description
In the dev guide module topic python API description, we require the no-main-docstr option, to prevent module docstrings from appearing in the landing page python API section. Having this option set for all our docs prevents us from directly linking to modules using single-backtick links, like we do for classes and methods.
I propose to remove the first paragraph in the callout note in this section, and the :no-main-docstr: from the example above it and all other examples where it is used. We also need a paragraph in the Python API Reference section about what should go into the module-level docstring, linking to the python module docstrings in "Documenting Python APIs with docstrings". Something to the effect of "Python modules should have a short top-level docstring describing the purpose of the module." Jonathan Sick had suggested to me that module docstrings should be kept short, and might have further suggestions here.
Our existing python module example has a much longer module docstring. Given the guidance from Jonathan Sick on keeping module docstrings short, I wonder how we would rework that example module? We also have a section on python module docstrings that could be reworded to reflect that a short docstring will be included in the python API docs.
This RFC came out of a discussion on a PR for the verify package, where a commandline interface needed a link to the python module it used. Creating that link means not having no-main-docstr set. For developers, having a short module docstring can be very helpful in understanding the purpose of that file, and I think it's useful to have those docstrings included in the package API docs.
Attachments
Issue Links
- relates to
-
DM-20455 Python module cross-reference links not working
- Invalid
-
- Done
- mentioned in
-
Page Loading...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Activity
I'd like to point out that the documentation linked to in the RFC description doesn't actually require :no-main-docstr:, it just says it's standard (i.e., it's informative, not normative).
That said, I think the proposed organization makes it hard to find the key information. I think that any (hopefully light!) prescriptions about what should go into the module docstring belong in the existing section on the docstrings page, since that's where somebody who is writing docstrings will look. The discussion in Python API Reference should be limited to how to include the existing docstring in the published docs and when it's appropriate to do so.
Krzysztof Findeisen
added a comment - I'd like to point out that the documentation linked to in the RFC description doesn't actually require :no-main-docstr: , it just says it's standard (i.e., it's informative, not normative).
That said, I think the proposed organization makes it hard to find the key information. I think that any (hopefully light!) prescriptions about what should go into the module docstring belong in the existing section on the docstrings page , since that's where somebody who is writing docstrings will look. The discussion in Python API Reference should be limited to how to include the existing docstring in the published docs and when it's appropriate to do so. As for the examples, the single-module case (which is what this RFC links to) is arguably the case where including the module docstring is redundant. In most cases where the docstring would be useful, including the DM-35326 discussion, there is one primary module and a bunch of secondary modules that for one reason or another weren't included in the main one, and it's the secondary modules whose purpose is unclear.
Krzysztof Findeisen
added a comment - - edited As for the examples, the single-module case (which is what this RFC links to) is arguably the case where including the module docstring is redundant. In most cases where the docstring would be useful, including the DM-35326 discussion, there is one primary module and a bunch of secondary modules that for one reason or another weren't included in the main one, and it's the secondary modules whose purpose is unclear. Jim Bosch: good point on being more explicit about which modules should have their API described in our docs and which shouldn't. I don't know if "implementation detail" modules shouldn't have a module docstring at all-I find those be useful when finding my way around a package-but you're right that they shouldn't be in the API docs. How to word that and where to put that is a good question.
Krzysztof Findeisen: Since there hasn't been much opposition to this, I'll try to come up with a proposed reworking of the dev guide, and see if that clears up your organization concern. There are multiple pages that will at least need tweaking.
John Parejko do you want to set a new end date for this RFC?
I'm certainly in favor of allowing package docstrings, but I think it's important to distinguish between publicly-visible modules that we expect users to directly import and more-or-less implementation-detail modules whose public symbols are all lifted to some outer package scope (see also RFC-653). The latter should still not have docstrings, and ideally shouldn't appear at all in our docs as modules, and I think that needs to be called out in the developer documentation and examples - we tend not to think about which of these a module actually is, and this is a good opportunity to improve that.