Three Dollar Quill

Okay, I did some work on writing today, and I did some more, but mostly I was working on getting an idea of how to write these docstrings. Here's where I ended up:

• Need to have autodoc, so use sphinx.ext.autodoc
• Sphinx-style docstrings are painful, so use sphinx.ext.napoleon.
• I think I prefer numpy-style docstrings for most things...
• But I don't want to double-annotate types, so I messed around and discovered that it's possible to mix docstring styles, to have google-style for Returns and Yields and numpy style for everything else.
• I think autodoc_typehints = "signature" in conf.py is doing something.

Other things I found:

• sphinx_autodoc_typehints and sphinx_toolbox.more_autodoc_typehints offer similar functionality (I believe one is a fork of the other), but I don't remember if I ran into a solid difference in my limited testing
• I couldn't get TypeVars to consistently do what I wanted, but things might be different in a proper codebase.
• These packages don't seem to put types on Yields fields.
• Apparently none of this code supports Receives, which is documented in the numpy style guide, but doesn't seem to exist in autodoc. So, it doesn't look nice no matter what I do.
• It is, however, possible to add custom fields, so I added these lines to napoleon_custom_sections in conf.py: ("Receives", "params_style"), and ("Type Parameters", "returns_style"). I figure the Type Parameters should go between Extended Summary and Parameters.
• autodoc just generally doesn't seem to match up with how the styleguides think you should be documenting generators.

With all of this research, now there's just a little more I want to check before I try to document MOTR...

• Starting in Python 3.9, I can do stuff like list[int]
• I believe it should be possible for me to use int | str style syntax in annotations; I may look into bumping MOTR's minimum Python version after the next release.

Anyway, all of that gives me stuff to guide my attempts to actually properly document MOTR. The general idea I have there is to write documentation that's good enough for fixing the design issues I hit, then look into adding a pylint stage to the current motrfile, unless I can find a flake8 plugin for stuff like "documented names match the names in the code". Maybe do those in the other order, actually, so I have a checklist to work through.

Anyway, I'm going to take care of some things, and then do a bit more writing. I don't want the night to get completely away from me again.

Good night.