Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-880

Allow package docstrings in python automodapi docs.

    XMLWordPrintable

Details

    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." jsick 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 jsick 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

          Activity

            tjenness Tim Jenness added a comment -

            Parejkoj do you want to set a new end date for this RFC?

            tjenness Tim Jenness added a comment - Parejkoj do you want to set a new end date for this RFC?
            tjenness Tim Jenness added a comment -

            Parejkoj can you give a status report on this RFC?

            tjenness Tim Jenness added a comment - Parejkoj can you give a status report on this RFC?
            tjenness Tim Jenness added a comment -

            What is blocking the adoption of this RFC?

            tjenness Tim Jenness added a comment - What is blocking the adoption of this RFC?
            tjenness Tim Jenness added a comment -

            Parejkoj any thoughts on this RFC? It's been open for over a year.

            tjenness Tim Jenness added a comment - Parejkoj any thoughts on this RFC? It's been open for over a year.

            I'm withdrawing this RFC, as I don't have time to cleanup the docs to deal with the suggestions given in comments above. If someone wants to do this in the future, I fully support them and would be happy to proofread something.

            Parejkoj John Parejko added a comment - I'm withdrawing this RFC, as I don't have time to cleanup the docs to deal with the suggestions given in comments above. If someone wants to do this in the future, I fully support them and would be happy to proofread something.

            People

              Parejkoj John Parejko
              Parejkoj John Parejko
              Jim Bosch, John Parejko, Jonathan Sick, Krzysztof Findeisen, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                Jenkins

                  No builds found.