Documentation

[James Kerns]

Figured I'd post here as I don't feel this counts as an "issue". 

Can we determine exactly what documentation style pydicom will have? It seems a good idea to introduce that streamlined consistency for 1.0.0. Also, the docstrings now aren't consistent. The question then is, what style is best? 

Python uses standard reST/Sphinx, which, considering pydicom's "pure python" bent, is a strong argument. This tends to not read well when using things like help in the interpreter, but looks good when built (github has a nice webhook to RTD: https://readthedocs.org/).

There's an interesting discussion of Sphinx/Numpy/Google formatting here: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html, which, interestingly, would allow us to use Google or Numpy formatting without any reST/Sphinx drawbacks. 

In summary then, again, the question is: What is pydicom's docstring style?

[Darcy Mason]

On Friday, November 28, 2014 12:19:13 AM UTC-5, James Kerns wrote:

Figured I'd post here as I don't feel this counts as an "issue". 

This raises a good question... this dev list was set up (IIRC) in part to overcome some shortcomings of the googlecode hosting, as it allowed easy delivery of push notifications etc.   I also wanted a place for possibly lengthy discussions on things like python 3 migration, complete refactoring of pydicom, creating more classes to enforce correct types when assigning data element values, etc.

However, perhaps the more github-ic (is there an equivalent to 'pythonic'?) way is to discuss through issues.  We can start here but maybe you should start an issue there, James, once we have a little more definition.  Sorry about any confusion, I'm still getting my head around the new systems and still need to close off the old ways with forwarding notices. 

 

Can we determine exactly what documentation style pydicom will have? It seems a good idea to introduce that streamlined consistency for 1.0.0. Also, the docstrings now aren't consistent. The question then is, what style is best? 

Python uses standard reST/Sphinx, which, considering pydicom's "pure python" bent, is a strong argument. This tends to not read well when using things like help in the interpreter, but looks good when built (github has a nice webhook to RTD: https://readthedocs.org/).

I agree with all these comments.  I don't like the plain-text readability of the sphinx docstring markup, really.   It's a little too intrusive.  But it's nice once fully built.   I did set up readthedocs a couple of days ago (pydicom.readthedocs.org), but still have to put the hook in to auto-build on github updates.

 

There's an interesting discussion of Sphinx/Numpy/Google formatting here: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html, which, interestingly, would allow us to use Google or Numpy formatting without any reST/Sphinx drawbacks. 

I'll take a look at that, sounds intriguing.

 

In summary then, again, the question is: What is pydicom's docstring style?

Well, let's see if we can define that, along with anyone who is interested and/or knowledgeable about these things...

Darcy

 

[Matthew Brett]

Hi,

I'm personally used to the numpy docstring format, and I use it in all
my projects. I find it particularly readable as plain text, and I
read docstrings as plain text much more often than looking them up in
the built docs, either from the interactive IPython prompt or when
reading the code. But the numpy docstrings also render nicely. You
probably saw already that this only needs the numpydoc sphinx
extension added to the sphinx docs.

Cheers,

Matthew

[Darcy Mason]

Had a reasonable read through the napoleon link James gave, and really like this ... so the question would be which of the two styles to go with.

I like either of them, but I would say I'm with Matthew in preferring the NumPy style.  I like to give decently long descriptions of the arguments, and in the NumPy style those start with less indentation, so are more likely to fit on one line.  Plus the underlined section headings stand out a bit more.  On the downside, it will be a little lengthy vertically for small, non-"API" functions with minimal need for documentation, but I think the better look for the important major docstrings would be worth it.

--
You received this message because you are subscribed to the Google Groups "pydicom-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pydicom-dev...@googlegroups.com.
To post to this group, send email to pydic...@googlegroups.com.
Visit this group at http://groups.google.com/group/pydicom-dev.
For more options, visit https://groups.google.com/d/optout.

[James Kerns]

Both Google and Numpy look better than, and don't seem that different than, standard Sphinx. I'm actually going to change my projects to use that napoleon extension. 

Long descriptions are a good thing! =) I do agree that the Numpy style is a little lengthy, but also does seem more appropriate if the descriptions are longer.

Next question is whether to document just the public API, or all functions/methods. Presumably, all private functions could use some sort of quick and dirty documentation, or, it could be mandated that all functions/methods are fully documented (or at least that's the goal). 

I'll open an issue on github so this all stays with the repo with an enhancement tag and link to here . 

[James Kerns]

Google and Numpy don't seem that different *compared to* Sphinx, sorry.