3 ms·
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 w
by danking00 7y ago
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
- pokeymcsnatch 7y agoA little off-topic, but as someone who's just started producing documentation in Sphinx, what are the problems/downsides that you've run in to? I've used it for two projects so far: documenting a relatively small python module, and for documenting a RESTful API. I do a lot of embedded work, so I'd like to use it as a place to document a piece of hardware in it's entirety, from schematics/layouts to firmware and build toolchains to actual use of the device. Do you (or anyone else reading this) have any comments on that use case? I think my main complaint at the moment is that it doesn't play nice with Markdown, so I had to re-format a bunch of pre-existing documentation for it to work in Sphinx. ReST seems to render alright in Gitlab though, so that's a plus.
- kfoley 7y agoSphinx should support Markdown, we're using the instructions at https://www.sphinx-doc.org/en/master/usage/markdown.html https://www.sphinx-doc.org/en/master/usage/markdown.html for our project and haven't had any issues. Haven't tried it yet but you should also be able to enable rst blocks through recommonmark so you get the best of both - https://recommonmark.readthedocs.io/en/latest/auto_structify.html#embed-restructuredtext https://recommonmark.readthedocs.io/en/latest/auto_structify...
- timothycrosley 7y agoThanks so much for this great feedback! I haven't done any speed optimization on portray yet - as both at work and online I tend to organize my own projects as small self contained repositories. Clearly there is a lot of room for improvement there, I have a lot of ideas to make it faster. You can manually define the modules for portray (which you probably figured out to get documentation rendering): https://timothycrosley.github.io/portray/docs/quick_start/4.-configuration/ https://timothycrosley.github.io/portray/docs/quick_start/4.... And, yes write now Markdown only. I will say - this was a week only project: https://timothycrosley.com/project-2-portray https://timothycrosley.com/project-2-portray so I think there's a good chance I could improve these points with one more week of time spent :) Thanks! ~Timothy
- danking00 7y agoYeah of course! In retrospect my initial post seems a bit neutral to negative. I'm really glad this project exists, I'm endlessly frustrated by Sphinx. I'll keep my eye on your project!
- scardine 7y agoIf you are on 3.7 you can add this import: from __future__ import annotations And then forward references don't need to be strings. I wonder if this could fix the generated page.