Hi all,
I don't really have a strong opinion on the doctstring format, but one
point that came to my mind is type annotations in Python 3.
It looks like there is generally strong uptake for these in the community,
and they have the benefit of increasingly strong tooling (e.g., static type
checkers, and more importantly IDEs like PyCharm). So to me it seems that
one shouldn't invest much time in adding or reformatting type info in
docstrings. Rather I would convert the codebase to Python 3 only and add
type annotations. Now that Python 2 is nearing EOL I think the time is ripe
for that.
Cheers,
Niko
On Sat, Aug 12, 2017 at 10:10 AM, Laurenz Wiskott via mdp-toolkit <
mdp-toolkit(a)python.org> wrote:
> Hello all,
>
> I think one should make the decission based on the current dominance of
> one style in MDP
> only if the dominance is really strong, so that a change of style would
> cost a lot of
> additional time. From what I have heard so far, this is not the case.
>
> Therefore, I suggest to think about what style we would prefer regardless
> of the current
> situation. And there I see two arguments:
>
> 1) Which style is generally dominating outside MDP but in the code base
> relevant for the
> users of MDP? In other words, what do we think will the users of MDP
> prefer. This
> argument holds only insofar as we think the users actually go into the
> code and read the
> documentation there. I think, if the code is well documented on
> web-pages, that should
> not be the case.
>
> 2) Which style do the current/future developers of MDP prefer? That seems
> to me the
> primary question.
>
> My preference is not very relevant here, but for me a plus for Google
> Style would be its
> clarity and compactness, see
> https://bwanamarko.alwaysdata.net/napoleon/format_exception.html, and a
> minus would be
> that it comes from Google (ideology!!).
>
> Best, Laurenz.
>
>
> On Sat, Aug 12, 2017 at 03:05:26AM +0200, Nils Mueller wrote:
> > Hey everyone,
> >
> > as Fabian has said:
> >
> > I have not noticed any prevalent NumPy Style, but I have not looked
> through all of the code. [1] [2]
> >
> > If we have not missed any aspects favoring the NumPy Style, I could
> agree that the decision on which style the docstrings are sychronised to is
> admittedly arguable and would best made with regard to the proportion of
> docstrings correctly documented in the NumPy Style.
> >
> > Regards,
> > Nils
> >
> > [1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMEN
> T.rst.txt
> > [2] http://sphinxcontrib-napoleon.readthedocs.io/en/latest/examp
> le_numpy.html
> >
> >
> >
> > -----Ursprüngliche Nachricht-----
> > Von: Fabian Schoenfeld [mailto:fabian@ini.ruhr-uni-bochum.de]
> > Gesendet: Donnerstag, 10. August 2017 16:07
> > An: Tiziano Zito <opossumnano(a)gmail.com>
> > Cc: Nils Mueller <Nils.Mueller(a)ini.ruhr-uni-bochum.de>;
> mdp-toolkit(a)python.org
> > Betreff: Re: [mdp-toolkit] Re: Reworking the mdp documentation
> >
> > Hi Titiano,
> >
> > the NumPy style was the runner-up in our discussions as well; the
> clarity of the Google style ended up tipping the bar in its favor for us.
> (Other than that they seem very similar and, in the end, mostly a matter of
> taste.)
> >
> > If the majority mdp already employs the NumPy style then I agree with
> you, it would be nonsense to re-write all of that when the real goal is to
> update the actual content of the documentation.
> >
> > However, when looking through different mdp nodes I don't really see the
> code using NumPy style for the docstrings..? I haven't looked through all
> the nodes but most documentation I've encountered seems free form? I also
> seem to remember Nils mentioning that there's no prevalent NumPy style
> being used?
> >
> >
> > Cheers,
> > Fabian
> >
> >
> >
> >
> > ----- Original Message -----
> > From: "Tiziano Zito" <opossumnano(a)gmail.com>
> > To: "Nils Mueller" <Nils.Mueller(a)ini.ruhr-uni-bochum.de>
> > Cc: mdp-toolkit(a)python.org, "Fabian Schoenfeld" <
> fabian(a)ini.ruhr-uni-bochum.de>
> > Sent: Tuesday, August 8, 2017 8:14:14 AM
> > Subject: [mdp-toolkit] Re: Reworking the mdp documentation
> >
> > Hi Nils, hi Fabian,
> >
> > I agree with your proposed plan. All looks good!
> >
> > The only discussion I'd like to have with the other MDP devs is about
> the docstring style. You are proposing to move to the Google style, MDP is
> currently using the NumPy style [1]. The NumPy style is very widespread in
> the scientific Python community, and that is the reason we chose it. Users
> recognize it, and, if I read correctly, even the napoleon Sphynx extension
> knows about it. So, in spite of being probably more widespread, but not in
> the scientific Python community, what are the advantages of the Google
> style as opposed to the NumPy style? On a side note: is it worth it to
> spend time in updating all docstrings from one style to another? Isn't this
> time better spent in updating the
> > *content* of the documentation, if anything at all?
> >
> > Ciao!
> > Tiziano
> >
> > [1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMEN
> T.rst.txt
> >
> > On Mon 07 Aug, 23:59, Nils Mueller <Nils.Mueller(a)ini.ruhr-uni-bochum.de>
> wrote:
> > >Hello everyone,
> > >
> > >as Fabian mentioned, I will quickly introduce you to the key features
> > >of what we have planned, as well as our current state:
> > >
> > >As of now the MDP documentation is generated by Sphinx, a Python
> > >software for quick and easy documentation generation that uses
> > >reStructuredText as a markup language and docutils for parsing and
> > >translating. [1] We propose to stick with Sphinx.
> > >
> > >One of the key features of Sphinx is its API for creating extensions.
> > >The current MDP documentation includes different extensions
> > >implementing several rather small modifications, i.e. internal API
> > >documentation links. A more recently developed feature of Sphinx is the
> > >apidoc tool for automatic generation of Sphinx sources that, using the
> > >autodoc extension, document a whole package in the style of other
> > >automatic API documentation tools. [2] This feature is not used in the
> > >current MDP documentation and we propose to use it to replace the
> > >current API documentation, as done in the documentation of popular
> Python software projects.
> > >
> > >The extension API of Sphinx also made it possible to adopt different
> > >docstring-styles, such as the Google Docstring Style, which are
> > >automatically parsed during the Sphinx build process by the Napoleon
> > >extension. [3] [4] [5] As Fabian mentioned, we are proposing to adopt
> > >the Google Docstring Style.
> > >
> > >The last major change we propose is the hosting of the documentation on
> > >readthedocs, which enables an automatic build process triggered by a
> > >commit to the Github repository of the MDP, a neat theme and widespread
> > >adoption by various software projects. [6]
> > >
> > >In short, these changes would make combine into a easily maintainable,
> > >modern and accessible documentation for the MDP.
> > >
> > >Currently we are working on extending the apidoc tool and integrating
> > >our changes seamlessly into the current MDP documentation. This is
> > >planned to result in a presentable example for which we will convert
> > >some of the docstrings of a local copy to the Google Style, then
> > >subsequently in conversion of the remaining docstrings.
> > >
> > >Regards,
> > >Nils
> > >
> > >[1] http://www.sphinx-doc.org/
> > >[2] http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
> > >[3]
> > >https://google.github.io/styleguide/pyguide.html?showone=Comments#Comme
> > >nts
> > >[4]
> > >http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.h
> > >tml [5] http://sphinxcontrib-napoleon.readthedocs.io/
> > >[6] https://readthedocs.org/
> > >
> > >-----Ursprüngliche Nachricht-----
> > >Von: Fabian Schoenfeld [mailto:fabian@ini.ruhr-uni-bochum.de]
> > >Gesendet: Montag, 7. August 2017 18:30
> > >An: mdp-toolkit(a)python.org
> > >Betreff: [mdp-toolkit] Reworking the mdp documentation
> > >
> > >Hi everyone,
> > >
> > >as you are probably aware we're currently in the process of revamping
> > >the mdp documentation. Nils here at the INI is working hard at setting
> > >up a new toolchain to make the docs more accessible and once that is
> > >done we also want to work on the documentation itself and add new
> > >tutorials for some of the standout features of mdp.
> > >
> > >Right now we're finishing the visual part and how to present the docs.
> > >Once this gets closer to being feature complete we'll upload it for
> > >everyone to take a look at (probably by opening an issue on the mdp git
> > >page, which as I understand is the usual way to discussing new
> features).
> > >
> > >Below you'll find a summary by Nils of where we are right now and what
> > >we're using for the docs. This is basically a heads up so that all mdp
> > >developers know about it and can weigh in with their opinions if they
> wish.
> > >
> > >Once it's set up users only have to adhere to the google style of
> > >documenting Python code* and the tool chain will take care of the rest
> > >by automatically generating the online documentation. We'd like to go
> > >with the google format of docstrings since we think it's a reasonable
> > >format that is very clean, readable, and has received widespread
> support.
> > >
> > >
> > >Cheers,
> > >Fabian
> > >
> > >
> > >
> > >_____________________
> > >* see for example:
> > >
> > >http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.h
> > >tml _______________________________________________
> > >mdp-toolkit mailing list
> > >mdp-toolkit(a)python.org
> > >https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
> > >_______________________________________________
> > >mdp-toolkit mailing list
> > >mdp-toolkit(a)python.org
> > >https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
> > _______________________________________________
> > mdp-toolkit mailing list
> > mdp-toolkit(a)python.org
> > https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
> > _______________________________________________
> > mdp-toolkit mailing list
> > mdp-toolkit(a)python.org
> > https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
> _______________________________________________
> mdp-toolkit mailing list
> mdp-toolkit(a)python.org
> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
>
