DM-54027: add docs on writing docs with type annotations #737
Conversation
TallJimbo
force-pushed
the
tickets/DM-54027
branch
7 times, most recently
from
5aaaee4 to
23d127e
Compare
Almost nobody knows that Sphinx normally pays no attention to your import statements, and I didn't even notice the existing text on this when I went to add new text on it.
TallJimbo
force-pushed
the
tickets/DM-54027
branch
from
23d127e to
bb20124
Compare
| .. note:: | ||
| Attributes without default values (or some sort of ``= RHS``) are not | ||
| included in documentation *at all*, except for those on `~dataclasses.dataclass` types. | ||
| Important instance attributes that cannot have a class-level default value should be made into properties so they can be documented. |
There was a problem hiding this comment.
This feels like a really significant recommendation to be making about Python code style for something that seems like a limitation in the documentation build system, but I also don't really see that we have a much of a choice; not documenting public attributes doesn't really seem like a viable option, either.
This is not clear from the Sphinx output unless you know what you're looking for, but nitpick mode complains if you don't use types.
TallJimbo
force-pushed
the
tickets/DM-54027
branch
from
dbbfc06 to
8112aed
Compare
| [sphinx] | ||
| nitpick_ignore = [ | ||
| ["py:class", "T"], # type variables don't resolve | ||
| ] |
There was a problem hiding this comment.
This recommendation works well enough for per-package builds, but I suspect it doesn't scale up to pipelines_lsst_io, and I'm not sure what to do about that. Maybe it's a moot point because it's hard to imagine pipelines_lsst_io ever running nitpick-clean.
There was a problem hiding this comment.
Correct. There is no way that nitpick is ever passing. (and now it's impossible because of the way the pybind11 docs from C++ aren't really known to sphinx).
No description provided.