4 ms·
We've historically done this as well. One issue we perpetually run into is that the docstrings get out of sync with the actual signature / types of the methods/
by weberc2 7y ago
We've historically done this as well. One issue we perpetually run into is that the docstrings get out of sync with the actual signature / types of the methods/etc that they purport to document. I suspect there are plugins that generate documentation from types such that there is less to keep synchronized. It is also unfortunate that Python projects have to set up infrastructure to build and publish documentation packages. I really like the effortlessness that Go's ecosystem brings--https://godoc.org https://godoc.org just reads your source code from your git repository, so there is are no explicit steps for building and publishing documentation.
- carapace 7y ago> the docstrings get out of sync with the actual signature / types of the methods/etc that they purport to document But that's on the devs, not Sphinx, eh?
- weberc2 7y agoIt's kind of on the whole dynamically typed model. If you can have static type annotations that are validated for correctness, then you can use those annotations to validate or generate your documentation. Python supports annotations and validation thereof via Mypy, and assuming the project takes advantage of these, then Sphinx could leverage them to validate/generate documentation.
- baylessj 7y agoWith Sphinx's Napoleon extension (https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#type-annotations https://www.sphinx-doc.org/en/master/usage/extensions/napole...) Python 3 type annotations will be added to the generated docstrings so you don't have to write the annotations both in the function definition and in its docstring. I've found this to be very helpful in keeping docs in sync with the code.