On 09/25/2016 03:20 AM, chitt...@uah.edu wrote:
On Sunday, September 11, 2016 at 3:56:36 PM UTC-5, chit...@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
--
https://mail.python.org/mailman/listinfo/python-list
