Fwd: Re: Reworking the mdp documentation
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@python.org> wrote:
- A - You raise a good point there Niko, Python 3 wasn't really on my radar. However, type annotations are just that: annotations of data type. How would that work in combination of explaining what the parameters actually do (and other things we'd like to add to the documentation)? Wouldn't that just be docstring-style-of-choice plus type annotations in the method definitions? In other words, using type annotations seems to me an additional option we have that is largely independent from the way we format docstrings? (Except that we'd introduce redundancy, or course.) Do you maybe have a link to a succinct example / comparison? - B - I'm rather opposed to the idea of stubfiles that would have to be created in addition to the normal doc- umentation :/ To me the documentation should be part of the normal workflow: you write your source code, you document it according to some agreed standard, and you're done. It's difficult enough to make people write clean code as it is, I don't think it'd be a good idea to have a whole additional process to go through for the documentation. It'd be the last thing everyone does and it'd be a hassle every time. I'm not saying that it's a bad thing to do, it just triggers all the warning lights on my pragmatism filter o_O -C - As for personal preference, my vote would go to the Google style; it seems a lot cleaner to me and easier to parse out the different parts and overall structure - which to me is what a docstring is all about: quick access to the information I need. I want to be able to scan it quickly and identify the part I'm actually interested in. When I look at Numpy Style examples that feels a lot less easy to do -- I strongly prefer the empty lines Google style uses as a delimiter. Cheers, Fabian From: "Stefan Richthofer" <Stefan.Richthofer@gmx.de> To: "Niko Wilbert" <mail@nikowilbert.de> Cc: mdp-toolkit@python.org Sent: Sunday, August 13, 2017 9:11:17 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation By putting the type annotations into stubfiles we can keep Python 2 workability. Cheers, Stefan Gesendet: Sonntag, 13. August 2017 um 12:58 Uhr Von: "Niko Wilbert" <mail@nikowilbert.de> An: mdp-toolkit@python.org Betreff: [mdp-toolkit] Fwd: Re: Reworking the mdp documentation 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@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:
mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
Hi everybody, in case it helps decide, I went through the code of some of the major python packages we might interface with, to check which docstrings they use: * Scikit-learn: NumPy style * NumPy/SciPy: NumPy style * Pandas: NumPy style * Matplotlib.: None * OpenAI’s gym: mixed * Google’s tensorflow: Google style Although this might make documenting a little easier for developers that are used to a certain docstring style, both styles seem about equally readable for the user to me (with a personal preference of the Google Style). I would also expect both styles to be supported by the tools we use, in the future. As Stefan mentioned before, using the NumPy style, we could save some work on developing extensions for Sphinx (by having the option to use numpydoc instead of napoleon), but with the downside of being dependent on that tool. I have a preference towards napoleon, because of this. Just to mention: The decision about type annotations does only influence the docstrings in the sense that we would not have to include type information in the docstrings (according to both styleguides), but probably should anyway. Regards, Nils Von: Fabian Schoenfeld [mailto:fabian.schoenfeld@ini.rub.de] Gesendet: Montag, 14. August 2017 11:09 An: mdp-toolkit@python.org Betreff: [mdp-toolkit] Re: Reworking the mdp documentation - A - You raise a good point there Niko, Python 3 wasn't really on my radar. However, type annotations are just that: annotations of data type. How would that work in combination of explaining what the parameters actually do (and other things we'd like to add to the documentation)? Wouldn't that just be docstring-style-of-choice plus type annotations in the method definitions? In other words, using type annotations seems to me an additional option we have that is largely independent from the way we format docstrings? (Except that we'd introduce redundancy, or course.) Do you maybe have a link to a succinct example / comparison? - B - I'm rather opposed to the idea of stubfiles that would have to be created in addition to the normal doc- umentation :/ To me the documentation should be part of the normal workflow: you write your source code, you document it according to some agreed standard, and you're done. It's difficult enough to make people write clean code as it is, I don't think it'd be a good idea to have a whole additional process to go through for the documentation. It'd be the last thing everyone does and it'd be a hassle every time. I'm not saying that it's a bad thing to do, it just triggers all the warning lights on my pragmatism filter o_O -C - As for personal preference, my vote would go to the Google style; it seems a lot cleaner to me and easier to parse out the different parts and overall structure - which to me is what a docstring is all about: quick access to the information I need. I want to be able to scan it quickly and identify the part I'm actually interested in. When I look at Numpy Style examples that feels a lot less easy to do -- I strongly prefer the empty lines Google style uses as a delimiter. Cheers, Fabian _____ From: "Stefan Richthofer" < <mailto:Stefan.Richthofer@gmx.de> Stefan.Richthofer@gmx.de> To: "Niko Wilbert" < <mailto:mail@nikowilbert.de> mail@nikowilbert.de> Cc: <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org Sent: Sunday, August 13, 2017 9:11:17 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation By putting the type annotations into stubfiles we can keep Python 2 workability. Cheers, Stefan Gesendet: Sonntag, 13. August 2017 um 12:58 Uhr Von: "Niko Wilbert" < <mailto:mail@nikowilbert.de> mail@nikowilbert.de> An: <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org Betreff: [mdp-toolkit] Fwd: Re: Reworking the mdp documentation 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 < <mailto:mdp-toolkit@python.org> mdp-toolkit@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> 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:
mdp-toolkit mailing list <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org <https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org <https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org <https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
Hi all, @Fabian: Yes, type annotations would be in addition to the info in the docstring, but I guess that in that case one wouldn't include any type information in the doctstrings. Stub files weren't on my radar, but I don't think they are worth the effort in this case (especially since Python, unlike JavaScript, is in the lucky position of having one official type annotation format). And dropping Python 2 support for new versions of MDP seems reasonable to me. Anyway, I think it is great that you guys want to improve the documentation. I'm fine with whatever you decide. Cheers, Niko On Mon, Aug 14, 2017 at 5:00 PM, Nils Mueller < Nils.Mueller@ini.ruhr-uni-bochum.de> wrote:
Since this thread hasn't seen more activity for a while and there hasn't been any major disagreement with our original plan - using Google style documentation strings and setting up a toolchain that updates the online documentation using Sphinx et. al. - we're back to implementing this and hopefully be able to make the toolchain available soon (if not the whole doc update). Cheers, Fabian From: "Niko Wilbert" <mail@nikowilbert.de> To: "Stefan Richthofer" <Stefan.Richthofer@gmx.de> Cc: "Nils Mueller" <Nils.Mueller@ini.ruhr-uni-bochum.de>, mdp-toolkit@python.org Sent: Tuesday, August 15, 2017 9:40:55 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation Thanks, I wasn't aware of these :-). Cheers, Niko On Tue, Aug 15, 2017 at 3:37 PM, Stefan Richthofer < Stefan.Richthofer@gmx.de > wrote: try this with mdp, e.g. the test suite if possible and see how useful the results are. Maybe it's at least a good starting point. Also, I want to check if it's possible (with reasonable effort) to make this info available to napoleon, similar to napoleon-typehints. Gesendet: Dienstag, 15. August 2017 um 10:32 Uhr Von: "Niko Wilbert" < mail@nikowilbert.de > An: "Nils Mueller" < Nils.Mueller@ini.ruhr-uni-bochum.de > Cc: mdp-toolkit@python.org Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Hi all, @Fabian: Yes, type annotations would be in addition to the info in the docstring, but I guess that in that case one wouldn't include any type information in the doctstrings. Stub files weren't on my radar, but I don't think they are worth the effort in this case (especially since Python, unlike JavaScript, is in the lucky position of having one official type annotation format). And dropping Python 2 support for new versions of MDP seems reasonable to me. Anyway, I think it is great that you guys want to improve the documentation. I'm fine with whatever you decide. Cheers, Niko On Mon, Aug 14, 2017 at 5:00 PM, Nils Mueller < Nils.Mueller@ini.ruhr-uni-bochum.de > wrote: BQ_BEGIN Hi everybody, in case it helps decide, I went through the code of some of the major python packages we might interface with, to check which docstrings they use: * Scikit-learn: NumPy style * NumPy/SciPy: NumPy style * Pandas: NumPy style * Matplotlib.: None * OpenAI’s gym: mixed * Google’s tensorflow: Google style Although this might make documenting a little easier for developers that are used to a certain docstring style, both styles seem about equally readable for the user to me (with a personal preference of the Google Style). I would also expect both styles to be supported by the tools we use, in the future. As Stefan mentioned before, using the NumPy style, we could save some work on developing extensions for Sphinx (by having the option to use numpydoc instead of napoleon), but with the downside of being dependent on that tool. I have a preference towards napoleon, because of this. Just to mention: The decision about type annotations does only influence the docstrings in the sense that we would not have to include type information in the docstrings (according to both styleguides), but probably should anyway. Regards, Nils Von: Fabian Schoenfeld [mailto: fabian.schoenfeld@ini.rub.de ] Gesendet: Montag, 14. August 2017 11:09 An: mdp-toolkit@python.org Betreff: [mdp-toolkit] Re: Reworking the mdp documentation - A - You raise a good point there Niko, Python 3 wasn't really on my radar. However, type annotations are just that: annotations of data type. How would that work in combination of explaining what the parameters actually do (and other things we'd like to add to the documentation)? Wouldn't that just be docstring-style-of-choice plus type annotations in the method definitions? In other words, using type annotations seems to me an additional option we have that is largely independent from the way we format docstrings? (Except that we'd introduce redundancy, or course.) Do you maybe have a link to a succinct example / comparison? - B - I'm rather opposed to the idea of stubfiles that would have to be created in addition to the normal doc- umentation :/ To me the documentation should be part of the normal workflow: you write your source code, you document it according to some agreed standard, and you're done. It's difficult enough to make people write clean code as it is, I don't think it'd be a good idea to have a whole additional process to go through for the documentation. It'd be the last thing everyone does and it'd be a hassle every time. I'm not saying that it's a bad thing to do, it just triggers all the warning lights on my pragmatism filter o_O -C - As for personal preference, my vote would go to the Google style; it seems a lot cleaner to me and easier to parse out the different parts and overall structure - which to me is what a docstring is all about: quick access to the information I need. I want to be able to scan it quickly and identify the part I'm actually interested in. When I look at Numpy Style examples that feels a lot less easy to do -- I strongly prefer the empty lines Google style uses as a delimiter. Cheers, Fabian From: "Stefan Richthofer" < Stefan.Richthofer@gmx.de > To: "Niko Wilbert" < mail@nikowilbert.de > Cc: mdp-toolkit@python.org Sent: Sunday, August 13, 2017 9:11:17 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation By putting the type annotations into stubfiles we can keep Python 2 workability. Cheers, Stefan Gesendet: Sonntag, 13. August 2017 um 12:58 Uhr Von: "Niko Wilbert" < mail@nikowilbert.de > An: mdp-toolkit@python.org Betreff: [mdp-toolkit] Fwd: Re: Reworking the mdp documentation 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@python.org > wrote: BQ_BEGIN 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:
mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ BQ_END _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ BQ_END _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
Hello everybody, in order to make sure our changes in the docstrings do not interfere with the code we would like to run some unit tests. Is there a way to gain access to a possibly existing test framework? Thanks in advance for helping out, Nils Von: Fabian Schoenfeld [mailto:fabian.schoenfeld@ini.rub.de] Gesendet: Mittwoch, 30. August 2017 17:05 An: mdp-toolkit@python.org Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Since this thread hasn't seen more activity for a while and there hasn't been any major disagreement with our original plan - using Google style documentation strings and setting up a toolchain that updates the online documentation using Sphinx et. al. - we're back to implementing this and hopefully be able to make the toolchain available soon (if not the whole doc update). Cheers, Fabian _____ From: "Niko Wilbert" <mail@nikowilbert.de <mailto:mail@nikowilbert.de> > To: "Stefan Richthofer" <Stefan.Richthofer@gmx.de <mailto:Stefan.Richthofer@gmx.de> > Cc: "Nils Mueller" <Nils.Mueller@ini.ruhr-uni-bochum.de <mailto:Nils.Mueller@ini.ruhr-uni-bochum.de> >, mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Sent: Tuesday, August 15, 2017 9:40:55 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation Thanks, I wasn't aware of these :-). Cheers, Niko On Tue, Aug 15, 2017 at 3:37 PM, Stefan Richthofer <Stefan.Richthofer@gmx.de <mailto:Stefan.Richthofer@gmx.de> > wrote:
Stub files weren't on my radar, but I don't think they are worth the effort in this case
There is another option to move type info out of docstrings, but keep Python 2 compatibility: Type comments https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-an... Tools that support PEP484 should be able to handle this format too. Anyway, there is a converter that can auto-generate actual stubfiles from type comments included in pytypes https://github.com/Stewori/pytypes There is another mode that can observe types during runtime and dump this info into stubfiles. I was going try this with mdp, e.g. the test suite if possible and see how useful the results are. Maybe it's at least a good starting point. Also, I want to check if it's possible (with reasonable effort) to make this info available to napoleon, similar to napoleon-typehints. Gesendet: Dienstag, 15. August 2017 um 10:32 Uhr Von: "Niko Wilbert" <mail@nikowilbert.de <mailto:mail@nikowilbert.de> > An: "Nils Mueller" <Nils.Mueller@ini.ruhr-uni-bochum.de> Cc: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Hi all, @Fabian: Yes, type annotations would be in addition to the info in the docstring, but I guess that in that case one wouldn't include any type information in the doctstrings. Stub files weren't on my radar, but I don't think they are worth the effort in this case (especially since Python, unlike JavaScript, is in the lucky position of having one official type annotation format). And dropping Python 2 support for new versions of MDP seems reasonable to me. Anyway, I think it is great that you guys want to improve the documentation. I'm fine with whatever you decide. Cheers, Niko On Mon, Aug 14, 2017 at 5:00 PM, Nils Mueller <Nils.Mueller@ini.ruhr-uni-bochum.de <mailto:Nils.Mueller@ini.ruhr-uni-bochum.de> > wrote: Hi everybody, in case it helps decide, I went through the code of some of the major python packages we might interface with, to check which docstrings they use: * Scikit-learn: NumPy style * NumPy/SciPy: NumPy style * Pandas: NumPy style * Matplotlib.: None * OpenAI’s gym: mixed * Google’s tensorflow: Google style Although this might make documenting a little easier for developers that are used to a certain docstring style, both styles seem about equally readable for the user to me (with a personal preference of the Google Style). I would also expect both styles to be supported by the tools we use, in the future. As Stefan mentioned before, using the NumPy style, we could save some work on developing extensions for Sphinx (by having the option to use numpydoc instead of napoleon), but with the downside of being dependent on that tool. I have a preference towards napoleon, because of this. Just to mention: The decision about type annotations does only influence the docstrings in the sense that we would not have to include type information in the docstrings (according to both styleguides), but probably should anyway. Regards, Nils Von: Fabian Schoenfeld [mailto:fabian.schoenfeld@ini.rub.de <mailto:fabian.schoenfeld@ini.rub.de> ] Gesendet: Montag, 14. August 2017 11:09 An: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Re: Reworking the mdp documentation - A - You raise a good point there Niko, Python 3 wasn't really on my radar. However, type annotations are just that: annotations of data type. How would that work in combination of explaining what the parameters actually do (and other things we'd like to add to the documentation)? Wouldn't that just be docstring-style-of-choice plus type annotations in the method definitions? In other words, using type annotations seems to me an additional option we have that is largely independent from the way we format docstrings? (Except that we'd introduce redundancy, or course.) Do you maybe have a link to a succinct example / comparison? - B - I'm rather opposed to the idea of stubfiles that would have to be created in addition to the normal doc- umentation :/ To me the documentation should be part of the normal workflow: you write your source code, you document it according to some agreed standard, and you're done. It's difficult enough to make people write clean code as it is, I don't think it'd be a good idea to have a whole additional process to go through for the documentation. It'd be the last thing everyone does and it'd be a hassle every time. I'm not saying that it's a bad thing to do, it just triggers all the warning lights on my pragmatism filter o_O -C - As for personal preference, my vote would go to the Google style; it seems a lot cleaner to me and easier to parse out the different parts and overall structure - which to me is what a docstring is all about: quick access to the information I need. I want to be able to scan it quickly and identify the part I'm actually interested in. When I look at Numpy Style examples that feels a lot less easy to do -- I strongly prefer the empty lines Google style uses as a delimiter. Cheers, Fabian _____ From: "Stefan Richthofer" < <mailto:Stefan.Richthofer@gmx.de> Stefan.Richthofer@gmx.de> To: "Niko Wilbert" < <mailto:mail@nikowilbert.de> mail@nikowilbert.de> Cc: <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org Sent: Sunday, August 13, 2017 9:11:17 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation By putting the type annotations into stubfiles we can keep Python 2 workability. Cheers, Stefan Gesendet: Sonntag, 13. August 2017 um 12:58 Uhr Von: "Niko Wilbert" <mail@nikowilbert.de <mailto:mail@nikowilbert.de> > An: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Fwd: Re: Reworking the mdp documentation 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@python.org <mailto:mdp-toolkit@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:
mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org <https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
Thanks for the link. I just gave it a quick look as yet, but it seems fit. Have a good rest of the weekend, Nils Von: Stefan Richthofer [mailto:Stefan.Richthofer@gmx.de] Gesendet: Freitag, 6. Oktober 2017 18:17 An: Nils Mueller <Nils.Mueller@ini.ruhr-uni-bochum.de> Cc: mdp-toolkit@python.org Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Running tests like described in http://mdp-toolkit.sourceforge.net/install.html#testing should do it I suppose. Or do you need something additional? -Stefan Gesendet: Freitag, 06. Oktober 2017 um 17:32 Uhr Von: "Nils Mueller" <Nils.Mueller@ini.ruhr-uni-bochum.de <mailto:Nils.Mueller@ini.ruhr-uni-bochum.de> > An: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Hello everybody, in order to make sure our changes in the docstrings do not interfere with the code we would like to run some unit tests. Is there a way to gain access to a possibly existing test framework? Thanks in advance for helping out, Nils Von: Fabian Schoenfeld [mailto:fabian.schoenfeld@ini.rub.de] Gesendet: Mittwoch, 30. August 2017 17:05 An: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Since this thread hasn't seen more activity for a while and there hasn't been any major disagreement with our original plan - using Google style documentation strings and setting up a toolchain that updates the online documentation using Sphinx et. al. - we're back to implementing this and hopefully be able to make the toolchain available soon (if not the whole doc update). Cheers, Fabian _____ From: "Niko Wilbert" <mail@nikowilbert.de <mailto:mail@nikowilbert.de> > To: "Stefan Richthofer" <Stefan.Richthofer@gmx.de <mailto:Stefan.Richthofer@gmx.de> > Cc: "Nils Mueller" <Nils.Mueller@ini.ruhr-uni-bochum.de <mailto:Nils.Mueller@ini.ruhr-uni-bochum.de> >, mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Sent: Tuesday, August 15, 2017 9:40:55 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation Thanks, I wasn't aware of these :-). Cheers, Niko On Tue, Aug 15, 2017 at 3:37 PM, Stefan Richthofer <Stefan.Richthofer@gmx.de <mailto:Stefan.Richthofer@gmx.de> > wrote:
Stub files weren't on my radar, but I don't think they are worth the effort in this case
There is another option to move type info out of docstrings, but keep Python 2 compatibility: Type comments https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-an... Tools that support PEP484 should be able to handle this format too. Anyway, there is a converter that can auto-generate actual stubfiles from type comments included in pytypes https://github.com/Stewori/pytypes There is another mode that can observe types during runtime and dump this info into stubfiles. I was going try this with mdp, e.g. the test suite if possible and see how useful the results are. Maybe it's at least a good starting point. Also, I want to check if it's possible (with reasonable effort) to make this info available to napoleon, similar to napoleon-typehints. Gesendet: Dienstag, 15. August 2017 um 10:32 Uhr Von: "Niko Wilbert" <mail@nikowilbert.de <mailto:mail@nikowilbert.de> > An: "Nils Mueller" <Nils.Mueller@ini.ruhr-uni-bochum.de <mailto:Nils.Mueller@ini.ruhr-uni-bochum.de> > Cc: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Re: Reworking the mdp documentation Hi all, @Fabian: Yes, type annotations would be in addition to the info in the docstring, but I guess that in that case one wouldn't include any type information in the doctstrings. Stub files weren't on my radar, but I don't think they are worth the effort in this case (especially since Python, unlike JavaScript, is in the lucky position of having one official type annotation format). And dropping Python 2 support for new versions of MDP seems reasonable to me. Anyway, I think it is great that you guys want to improve the documentation. I'm fine with whatever you decide. Cheers, Niko On Mon, Aug 14, 2017 at 5:00 PM, Nils Mueller <Nils.Mueller@ini.ruhr-uni-bochum.de <mailto:Nils.Mueller@ini.ruhr-uni-bochum.de> > wrote: Hi everybody, in case it helps decide, I went through the code of some of the major python packages we might interface with, to check which docstrings they use: * Scikit-learn: NumPy style * NumPy/SciPy: NumPy style * Pandas: NumPy style * Matplotlib.: None * OpenAI’s gym: mixed * Google’s tensorflow: Google style Although this might make documenting a little easier for developers that are used to a certain docstring style, both styles seem about equally readable for the user to me (with a personal preference of the Google Style). I would also expect both styles to be supported by the tools we use, in the future. As Stefan mentioned before, using the NumPy style, we could save some work on developing extensions for Sphinx (by having the option to use numpydoc instead of napoleon), but with the downside of being dependent on that tool. I have a preference towards napoleon, because of this. Just to mention: The decision about type annotations does only influence the docstrings in the sense that we would not have to include type information in the docstrings (according to both styleguides), but probably should anyway. Regards, Nils Von: Fabian Schoenfeld [mailto:fabian.schoenfeld@ini.rub.de <mailto:fabian.schoenfeld@ini.rub.de> ] Gesendet: Montag, 14. August 2017 11:09 An: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Re: Reworking the mdp documentation - A - You raise a good point there Niko, Python 3 wasn't really on my radar. However, type annotations are just that: annotations of data type. How would that work in combination of explaining what the parameters actually do (and other things we'd like to add to the documentation)? Wouldn't that just be docstring-style-of-choice plus type annotations in the method definitions? In other words, using type annotations seems to me an additional option we have that is largely independent from the way we format docstrings? (Except that we'd introduce redundancy, or course.) Do you maybe have a link to a succinct example / comparison? - B - I'm rather opposed to the idea of stubfiles that would have to be created in addition to the normal doc- umentation :/ To me the documentation should be part of the normal workflow: you write your source code, you document it according to some agreed standard, and you're done. It's difficult enough to make people write clean code as it is, I don't think it'd be a good idea to have a whole additional process to go through for the documentation. It'd be the last thing everyone does and it'd be a hassle every time. I'm not saying that it's a bad thing to do, it just triggers all the warning lights on my pragmatism filter o_O -C - As for personal preference, my vote would go to the Google style; it seems a lot cleaner to me and easier to parse out the different parts and overall structure - which to me is what a docstring is all about: quick access to the information I need. I want to be able to scan it quickly and identify the part I'm actually interested in. When I look at Numpy Style examples that feels a lot less easy to do -- I strongly prefer the empty lines Google style uses as a delimiter. Cheers, Fabian _____ From: "Stefan Richthofer" < <mailto:Stefan.Richthofer@gmx.de> Stefan.Richthofer@gmx.de> To: "Niko Wilbert" < <mailto:mail@nikowilbert.de> mail@nikowilbert.de> Cc: <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org Sent: Sunday, August 13, 2017 9:11:17 PM Subject: [mdp-toolkit] Re: Reworking the mdp documentation By putting the type annotations into stubfiles we can keep Python 2 workability. Cheers, Stefan Gesendet: Sonntag, 13. August 2017 um 12:58 Uhr Von: "Niko Wilbert" <mail@nikowilbert.de <mailto:mail@nikowilbert.de> > An: mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> Betreff: [mdp-toolkit] Fwd: Re: Reworking the mdp documentation 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@python.org <mailto:mdp-toolkit@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:
mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list <mailto:mdp-toolkit@python.org> mdp-toolkit@python.org <https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/ _______________________________________________ mdp-toolkit mailing list mdp-toolkit@python.org <mailto:mdp-toolkit@python.org> https://mail.python.org/mm3/mailman3/lists/mdp-toolkit.python.org/
participants (4)
-
Fabian Schoenfeld -
Niko Wilbert -
Nils Mueller -
Stefan Richthofer