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. How do we want to decide which format to use going forward? Get the docs started and try out the different docstring formats? I'm +1 to using sphinx-style docstrings but could likely be persuaded to use something different as long as it doesn't require too much custom code. We have enough custom tools as it is and I'd rather use something standard for api docs. Tim
signature.asc
Description: PGP signature
_______________________________________________ qa-devel mailing list qa-de...@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/qa-devel
