4 ms·

My team at present use sphinx-doc[1] and generate both HTML and PDF. We write the documentation as part of the code using docstring and then other documents man

My team at present use sphinx-doc[1] and generate both HTML and PDF. We write the documentation as part of the code using docstring and then other documents manually in rst. We use Sphinx plugin to automatically generate document from code. I will give portray a try and see. Is there any comparison between Sphinx-doc and portray? [1] http://www.sphinx-doc.org/en/master/ http://www.sphinx-doc.org/en/master/

DanFeldman 7y ago
Which plugin do you use to go docstring->docs? I found it difficult out of the box to determine w/ Sphinx how to get everything to play nice.
- susam 7y ago
  I use sphinx-apidoc[1] command to extract docstrings from code and create Sphinx documentation files out of them. Enter this command to look for modules in a package, say, foopkg, and create .rst files to generate documentation for each module in the package and subpackages: sphinx-apidoc --module-first -o docs/api foopkg I am assuming that the Sphinx documentation project resides in a directory named docs. Each .rst file would contain automodule directives for Sphinx to automatically pull docstrings from foopkg and render them in the generated documentation. However, for Sphinx to understand these automodule directives, the autodoc[2] extension must be enabled in docs/conf.py. extensions = ['sphinx.ext.autodoc'] If the documentation is written using Google style or NumPy style docstrings, then the napolean[3] extension must also be enabled. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] The sphinx-apidoc command above would also write a file named docs/api/modules.rst which would be used to render the starting page of the automatically generated API documentation. So include this docs/api/modules.rst with the Sphinx toctree directive from the some other page that the user is likely to visit. For example, the start page of the project documentation would likely be rendered from `docs/index.rst`, so add this to `docs/index.rst`: API --- .. toctree:: api/modules Now render the documentation with Sphinx normally: cd docs && make html [1]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [3]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html https://www.sphinx-doc.org/en/master/usage/extensions/napole...
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 ago
    It'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 ago
  With 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.
timothycrosley 7y ago
The biggest differences between Sphinx-doc and portray: - Markdown - Zero Config required - Focus on Simplicity https://timothycrosley.com/project-2-portray https://timothycrosley.com/project-2-portray goes into why I created the project and how I viewed the current state of Python documentation tool.

DanFeldman 7y ago

Which plugin do you use to go docstring->docs? I found it difficult out of the box to determine w/ Sphinx how to get everything to play nice.

susam 7y ago
I use sphinx-apidoc[1] command to extract docstrings from code and create Sphinx documentation files out of them. Enter this command to look for modules in a package, say, foopkg, and create .rst files to generate documentation for each module in the package and subpackages: sphinx-apidoc --module-first -o docs/api foopkg I am assuming that the Sphinx documentation project resides in a directory named docs. Each .rst file would contain automodule directives for Sphinx to automatically pull docstrings from foopkg and render them in the generated documentation. However, for Sphinx to understand these automodule directives, the autodoc[2] extension must be enabled in docs/conf.py. extensions = ['sphinx.ext.autodoc'] If the documentation is written using Google style or NumPy style docstrings, then the napolean[3] extension must also be enabled. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] The sphinx-apidoc command above would also write a file named docs/api/modules.rst which would be used to render the starting page of the automatically generated API documentation. So include this docs/api/modules.rst with the Sphinx toctree directive from the some other page that the user is likely to visit. For example, the start page of the project documentation would likely be rendered from `docs/index.rst`, so add this to `docs/index.rst`: API --- .. toctree:: api/modules Now render the documentation with Sphinx normally: cd docs && make html [1]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html [3]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html https://www.sphinx-doc.org/en/master/usage/extensions/napole...

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 ago
  It'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 ago
With 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.

timothycrosley 7y ago

The biggest differences between Sphinx-doc and portray: - Markdown - Zero Config required - Focus on Simplicity https://timothycrosley.com/project-2-portray https://timothycrosley.com/project-2-portray goes into why I created the project and how I viewed the current state of Python documentation tool.