Hacker News new | past | comments | ask | show | jobs | submit login

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/

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 just reads your source code from your git repository, so there is are no explicit steps for building and publishing documentation.

With Sphinx's Napoleon extension (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.

> 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?

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.

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.

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`:


  .. toctree::

Now render the documentation with Sphinx normally:

  cd docs && make html
[1]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

[2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

[3]: https://www.sphinx-doc.org/en/master/usage/extensions/napole...

The biggest differences between Sphinx-doc and portray:

- Markdown - Zero Config required - Focus on Simplicity

https://timothycrosley.com/project-2-portray goes into why I created the project and how I viewed the current state of Python documentation tool.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact