On 04/17/2014 12:09 PM, Tim Flink wrote:
On Thu, 17 Apr 2014 10:03:24 -0400 (EDT)
Kamil Paral <kpa...@redhat.com> wrote:
https://pythonhosted.org/an_example_pypi_project/sphinx.html#auto-directives
I'm not suggesting that we drop everything and fix all the
docstrings right now but I am suggesting that we start following
the sphinx docstring format for new code and fix other-formatted
docstrings as we come across them.
Any objections?
Well, my only objection is, that the Sphinx format has IMHO the
worst impact on how docstrings look.
That is my impression as well [1]. The improved versions of Markdown
are more legible and easier to remember than ReST (+Sphinx) [2].
OTOH, there are certain Sphinx features that look really great (for
example documentation of attributes or global variables). So let's
try it.
This gets down to personal preference but in general, I prefer ReST to
markdown.
I thought that we had already decided to use sphinx when mike did his
documentation tool survey a couple of months ago.
Maybe it is just me, but I use help() more often than html docs.
The Spyder editor shows HTML output of docstrings, even though it
seems it uses plain ReST conversion instead of Sphinx conversion.
But other than that, I have no issues.
I played with it a little and the syntax is quite complex. If we are
to use it, we will need at least:
1. basic sphinx config committed into the repository
2. some instructions in the readme how to generate the docs
Yeah, my plan is to have sphinx docs live in the same repo as
libtaskotron so changes can be built locally before submitting any
patches.
"build docs" sounds like a reasonable section to have in the dev
documentation.
so that we can at least generate the docs locally and look at it
before posting the patch. As Tim already said, sphinx is pretty
strict in its syntax.
There is one more alternative, I think - use Sphinx for docs
generation, but keep the docstrings free-form (I assume there must be
an option in Sphinx to do that). That way we lose some pretty
formatting, but won't be forced to adhere to a particular syntax.
I put an example of the output from both sphinx-style docstrings and
freeform docstrings up on fedorapeople:
http://tflink.fedorapeople.org/taskotron/test-libtaskotron-docs/library.html
It sounds like the general consensus is that sphinx-style docstrings
are ugly but generate nice html output and it's not clear whether the
ugly-ness of the docstrings is worth the nice html api docs.
My 2 cents: The sphinx docstrings are not that bad, and the HTML output
in places like readthedocs.org is quite good. Besides, a good deal of
python projects fully embrace sphinx, precisely the reason why we
migrated all autotest, virt-test and related projects docstrings.
Example straight from virt-test:
http://virt-test.readthedocs.org/en/latest/api/modules.html
From avocado:
http://avocado-framework.readthedocs.org/en/latest/api/modules.html
Besides, rst is a quite capable language to write great non API
documentation and keep it in tree, using sphinx as well. So with one
solution, you get it all. Another reason why having not-so-pretty
docstrings in this case is worth the effort.
_______________________________________________
qa-devel mailing list
qa-de...@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/qa-devel
