docstrings | use Python-like docstrings

I fixed the issue. It was giving a "no module found" error.

Thanks to @mzjin's answer in the comments: this link describes that it is possible since v0.4.

The below example is given in the link, which is exactly what I was looking for.

maintainer here! :wave:

The short answer is no you cannot configure Black to fix line length issues in docstrings currently.

It's not likely Black will split or merge lines in docstrings as it would be far too risky, structured data can and does exist in docstrings. While I would hope the added newlines wouldn't break the consumers it's still a valid concern.

There's currently an open issue asking for this (although it also wants the line length limit for docstrings and strings to be 79) GH-2289. You can also read GH-1713 which is about splitting comments (and likewise has mixed feelings from maintainers).

For the time being, perhaps you can look into https://github.com/PyCQA/docformatter which does seem to wrap docstrings (see the --wrap-descriptions and --wrap-summaries options)

^{P.S. if you're curious whether we'll add a flag to split docstrings or comments, it's once again unlikely since we seek to minimize formatting configurability. Especially as the pre-existing flags only disable certain elements of Black's style (barring --line-length which exists as there's no real consensus what it should be). Feel free to state your arguments in the linked issues tho!}

As proposed in comment from @mzjn, I used sphinxcontrib-restbuilder for this purpose. Hyperlinks work, this is perfect for my need.

I applied it on the sphinx documentation of a public project of mine, and uploaded it on this github repo for those willing to have a look.

Click on index.rst and follow the read. There do be some glitches. The API is documented in api.rst. This is really this part that is of interest for me. I think it is nice enough.

Docstrings in Python must be regular string literals.

This is pretty easy to test - the following program does not show the docstring:

currently there is no such feature -- but in flake8 5.x (the next released version) there will be a (name pending) --require-plugins option

your best bet at the moment is to either (1) search pip freeze for flake8-docstrings (2) search flake8's --version output for flake8-docstrings

You can assign bar.name to self.name. Same goes for the docstring with the __doc__ attribute of the class:

Putting the type as a type hint and as part of the docstring would be redundant. It is also prone to human errors since one could easily forget updating one of them, thus effort is constantly needed to keep them both in sync.

The documentation for type hints also mentions it:

Docstrings. There is an existing convention for docstrings, based on the Sphinx notation (:type arg1: description). This is pretty verbose (an extra line per parameter), and not very elegant. We could also make up something new, but the annotation syntax is hard to beat (because it was designed for this very purpose).

But all of this depends on your usecase.

• If you are using a static-type checker such as MyPy (e.g. it would fail if you passed an int 123 to a variable with type hint str) or an IDE such as PyCharm (e.g. it would highlight inconsistencies between type hint and passed arguments), then you should keep on using type hints. This is the preferable way, as it points out possible errors in the code you've written.
• If you are using tools such as Sphinx, or Swagger, or something else, note that these tools display your classes and methods along with their docstrings for the purposes of documentation. So if you want to maintain such documentation for clarity to other readers and want to have the types included, then you might want to put the type hint in the docstring as well. But if you think such detail isn't needed as most of the time only the description in the docstring is relevant, then there is no need to add the type hint in the docstring.

In the long run, the more sustainable way is to have those tools (Sphinx, Swagger, etc.) use the type hint as part of the documentation instead of relying solely on the text in the docstring. For sphinx, I found this library sphinx-autodoc-typehints that performs it already.

Allowing you to migrate from this:

I agree with mzjn that your example doesn't give much to go on, but I'll hazard a couple of guesses:

Appending to apidoc stub pages

The docs/exampleproject.rst and docs/modules.rst stub files get generated automatically by sphinx-apidoc. Then you manually append your own content (a .. print_notes_attached_to_topic:: directive) into those.

This will be problematic, because every time sphinx-apidoc extracts the Python docstrings to rebuild its stub pages, your chunk is overwritten/lost. I'd never try and mix my own content into pages owned/generated by an extension - they can sit side-by-side, but separate, e.g. put all your directives in a ./docs/all-my-print-notes.rst page.

That said, if you want to complicate your life, then post-process. Amend the Sphinx makefile to detect stub page changes and trigger a Bash or Python script that plops your custom content on the end. Cleanest if done indirectly -- a single include directive goes in the stub page so that your custom content can remain isolated elsewhere.

The Jinja2 templates for autodoc and autosummary (in ./site-packages/sphinx/templates/apidoc/ & ./site-packages/sphinx/ext/autosummary/templates/) offer limited customization, but really only good for layout and static content.

Your Sphinx extension

The functionally you want sounds a lot like sphinx.ext.todo. Your .. attach_to_topic:: directives are scattered throughout the Python module docstrings (equivalent to .. todo:: directives) and your .. print_notes_attached_to_topic:: directives collect up those chunks into "a linear order" (equivalent to .. todolist::).

Luckily for you, the docs about creating extensions gives that very example which you can adapt to your needs. Your extension will have one extra feature, because it provides a :topic: option to tag/classify each .. todo:: item, and also to limit the scope of each .. todolist:: collation.