sphinx (or other means to document python)
jmp
jeanmichel at sequans.com
Mon Sep 26 09:16:12 EDT 2016
On 09/25/2016 03:20 AM, chitturk at uah.edu wrote:
> On Sunday, September 11, 2016 at 3:56:36 PM UTC-5, chit... at uah.edu wrote:
> (about being frustrated with sphinx)
>
> I _remain_ frustrated - even as I finally figured out how to use it (thanks to a complete example from a friend)
>
> sphinx is very picky about spaces, lines - I had a line with some math formula spaces and tabs (after r''' - and sphinx kept ignoring that line
>
> when it works, the documentation (my preference is LaTeX) is great - the procedure for embedding the documentation as doctrings can be difficult, at times
>
> noweb is considerably simpler - but does not allow for the extraction
> of docstrings/comments - and does provide for a fairly painless way to combine comments, documentation along with code
>
Hi,
Keep in mind sphinx has a greater scope than writing docs from/for
python. You could use sphinx to document anything.
That why it's not that straightforward to build doc from the source
code. Yet it's possible with some scripts available on the internet. But
it looks like you've managed to find out.
Ultimately, sphinx is designed to write good documentation, and is
slightly overkill if you want to build docs only from the source code.
But keep in mind that this kind of doc tend to be poor.
If you take a look at the python documentation, the paramount of good
documentation :) you'll notice it's not generated from the code docstrings.
For api reference documentation, the source code is sometimes the best
option.
jm
More information about the Python-list
mailing list