Tried this on our project, GitHub.com/hail-is/hail.<p>Sphinx is a persistent thorn in our side, but we've made it work. A couple things I had to do to get this working:<p>- something thinks a filename with dots (e.g. example.8bits.bgen) means there is a python module that needs to be imported (e.g. example), and fails when that does not exist; we have files like this in a data directory<p>- I could not quickly figure out how to ignore files, so I had to delete a Sphinx conf.py file.<p>- Sphinx resolves the _templates folder relative to where it is called, not relative to the doc string's source file, so I had to add several symlinks (rather than manually edit every doc string).<p>---<p>OK docs are generating. Quite slow, maybe a couple minutes. Looks like one core is at 100% during this process. We've got ~400 files. Maybe its parsing some data files? The whole directory is 318 MB.<p>---<p>Now I'm looking at the docs.<p>First thing I notice is that Python type hint forward references break everything. Consider:<p><pre><code> class GroupedMatrixTable(
parent: 'MatrixTable',
...
</code></pre>
The generated doc page is missing the class name and the entire class definition is inlined as a preformatted block (with highlighting :shrug:).<p>All my python function def's seem to be missing the function name?<p>No arg functions look really weird<p><pre><code> def (
)
</code></pre>
So all our docs are in ReST (thanks Sphinx :|). This means they're not valid Markdown. It seems that invalid markdown in a class doc string can break the formatting of all the methods (presenting them again as one reformatted block).<p>---<p>On the bright side, the mobile version looks great and the search works better than my experience with Sphinx.<p>EDIT: formatting
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.<p>I will give portray a try and see.<p>Is there any comparison between Sphinx-doc and portray?<p>[1] <a href="http://www.sphinx-doc.org/en/master/" rel="nofollow">http://www.sphinx-doc.org/en/master/</a>
This is great! You hit the need for configless docsites that many Pythonistas who are in data science and research have: we write a lot of experimental and prototype code. Docstring documentation in itself feels like a considerable investment in these contexts so anything that helps publication without any hassle is more than welcome.<p>Are you planning to support Restructured Text next to Markdown? I find ResT is used more often (in the machine learning ecosystem at least).
I just used this on a random project I happen to be building documentation for. I'm pretty in love with the minimalism of 'portray'. I wish there was a chance to get my team to use it, but I'll definitely be using it in my personal projects going forward!
I was super pumped by this, and took some time to look into pdoc3 too.<p>- <a href="https://github.com/pdoc3/pdoc/issues/87" rel="nofollow">https://github.com/pdoc3/pdoc/issues/87</a><p>- <a href="https://github.com/pdoc3/pdoc/issues/64" rel="nofollow">https://github.com/pdoc3/pdoc/issues/64</a><p>That's a hard pass from me. I'm not going to link my employer's name (much less my own name) to anything with a swastika on it.