sphinx (or other means to document python)

[jmp]

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