Tried this on our project, GitHub.com/hail-is/hail.

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:

- 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

- I could not quickly figure out how to ignore files, so I had to delete a Sphinx conf.py file.

- 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).

---

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.

---

Now I'm looking at the docs.

First thing I notice is that Python type hint forward references break everything. Consider:

    class GroupedMatrixTable(
        parent: 'MatrixTable',
        ...

The generated doc page is missing the class name and the entire class definition is inlined as a preformatted block (with highlighting :shrug:).

All my python function def's seem to be missing the function name?

No arg functions look really weird

    def (
    )

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).

---

On the bright side, the mobile version looks great and the search works better than my experience with Sphinx.

EDIT: formatting