Coding 2020-09-30

By Max Woerner Chase

I added some more documentation, and found a new gripe about Sphinx. One of the things Sphinx does for "data" members by default is to include their value in the generated documentation. I knew this, from elsewhere that I disabled it. The automodule directive, as near as I can tell, and I would like to be wrong, invokes the other directives as needed, with no way to control what options it passes.

This means that, when I document my stream types, I end up with gunk at the end of the entry like "alias of Union[cryptopals.sized_iterable.ExactSizedIterable[NewType.<locals>.new_type], cryptopals.sized_iterable.ApproximateSizedIterable[NewType.<locals>.new_type]]". No hyperlinks, no nothing. In the current documentation, this comes right after some stuff I wrote manually that presents as the proper types, with links.

I want to be wrong about this as well, but I believe having explicit entries for these definitions, to suppress the annotation, would cause the definitions to be grouped independently from the rest of the module, so if I want to avoid that, I need to document every member in order.

After inspecting Sphinx's sourcecode, I have news! Is it good news? Bad news? It's news!

If I'm reading this right, I was incorrect in assuming that the :annotation: directive would suppress the generated documentation of the value. So the good news is that I don't have to try to do this, because the bad news is that I apparently can't! News!

It's midnight and I'm not taking this well, possibly because I strained my shoulder earlier learning how to do creative stuff that doesn't involve typing.

I'm going to leave this as is and come back to it tomorrow, because I may want to sleep, but I don't want to admit defeat.

Good night.