Re: [Rdkit-discuss] another request for feedback on a new python API documentation format

[Greg Landrum]

Hi Maciek,

The old docs are all still online. Since there aren't links, you just need
to know the URL scheme:

http://rdkit.org/RDKit_Docs.2017_09_1.tgz
http://rdkit.org/RDKit_Docs.2016_03_1.tgz

note that there are almost always only the "_1.tgz" version available; the
patch releases don't normally affect the documentaiton.

-greg



On Tue, May 8, 2018 at 3:00 PM Maciek Wójcikowski 
wrote:

> Hi Greg,
>
> Speaking about the new docs - would it be possible to have documentation
> for few stable releases back, like 2017.09, 2017.03, etc. Recently I was
> trying to establish the changes in RDKit's API and ended up using git
> blame, whereas I could be able to get that info from changing the release
> on the docs.
>
> 
> Pozdrawiam,  |  Best regards,
> Maciek Wójcikowski
> mac...@wojcikowski.pl
>
> 2018-05-02 11:17 GMT+02:00 David Cosgrove :
>
>> Hi Greg,
>> After a quick poke about, I think the new documentation looks great in
>> general.  If a change is forced on you, then I suggest you just do it in a
>> way that makes your life as easy as possible.  If people don't like it,
>> they can always put the effort in to do something different and then I
>> expect they'll quickly come round to realising that your way is perfectly
>> fine.  One way of fixing the docstring formatting would be to put
>> instructions and a couple of examples somewhere handy and ask people to fix
>> problems when they encounter them as they read the docs.  That should be a
>> small effort from each person that would hopefully fix the important ones
>> quickly in a self-prioritising manner.
>> Thanks for putting the time into this,
>> Dave
>>
>>
>> On Wed, May 2, 2018 at 8:40 AM, Greg Landrum 
>> wrote:
>>
>>> Dear all,
>>>
>>> Just over a year ago I asked for feedback on a new documentation format
>>> for the RDKit python API:
>>> https://www.mail-archive.com/rdkit-discuss@lists.sourceforge.net/msg06688.html
>>> Some useful feedback came in on that thread (thanks to those who replied
>>> there and in private email), but I ran out of time/motivation to spend time
>>> on this.
>>>
>>> With my motivation recharged thanks to the "fun" of using epydoc to
>>> document the last release, I revisited the topic this weekend and actually
>>> made some progress.[1] I'd like to gather a second round of feedback on
>>> that.
>>>
>>> The documentation is here:
>>> http://rdkit.org/docs_temp/index.html
>>> The API docs (which are where the biggest changes are) are here:
>>> http://rdkit.org/docs_temp/api-docs.html
>>>
>>> To address some of the things raised last time:
>>> - This really isn't optional. It's been more than a decade since epydoc
>>> was updated and it requires python 2.7.
>>> - My previous attempt to auto-generate docs used pdoc (
>>> https://github.com/BurntSushi/pdoc). That project also seems to have
>>> died, so it's not really an option.
>>> - Based upon the two factors above I decided to use the autodoc
>>> functionality that's part of Sphinx. It's not perfect, but it's supported
>>> (and seems likely to continue to be so since it's part of Sphinx)
>>>
>>> - The docs now have a search box
>>>
>>> - We've lost the overview (list of classes/functions/etc) that epydoc
>>> provides. There likely is a way to do this with sphinx, but I haven't
>>> managed to get it to work yet
>>>
>>> - Formatting: Some of the docstrings end up looking pretty good, others
>>> are awful. Here's a module that demonstrates both sides of the coin:
>>> http://rdkit.org/docs_temp/source/rdkit.Chem.AtomPairs.Pairs.html#module-rdkit.Chem.AtomPairs.Pairs
>>> Fixing this is "just" a matter of editing the doc strings. This is
>>> reasonably mechanical, but unfortunately not automatable, work. It should
>>> be done, but in the meantime the broken docstrings aren't completely
>>> useless.
>>>
>>> There's also a github issue for this:
>>> https://github.com/rdkit/rdkit/issues/1656
>>> I'm doing the work on this branch:
>>> https://github.com/greglandrum/rdkit/tree/dev/usinx_sphinx_autodoc
>>>
>>> -greg
>>> [1] Remember how I said I was going to take a short break and do
>>> something fun? This isn't that.
>>>
>>>
>>>
>>> --
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>>> ___
>>> Rdkit-discuss mailing list
>>> Rdkit-discuss@lists.sourceforge.net
>>> https://lists.sourceforge.net/lists/listinfo/rdkit-discuss
>>>
>>>
>>
>>
>> --
>> David Cosgrove
>> Freelance computational chemistry and chemoinformatics developer
>> http://cozchemix.co.uk
>>
>>
>>
>> --
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> 

Re: [Rdkit-discuss] another request for feedback on a new python API documentation format

[Maciek Wójcikowski]

Hi Greg,

Speaking about the new docs - would it be possible to have documentation
for few stable releases back, like 2017.09, 2017.03, etc. Recently I was
trying to establish the changes in RDKit's API and ended up using git
blame, whereas I could be able to get that info from changing the release
on the docs.


Pozdrawiam,  |  Best regards,
Maciek Wójcikowski
mac...@wojcikowski.pl

2018-05-02 11:17 GMT+02:00 David Cosgrove :

> Hi Greg,
> After a quick poke about, I think the new documentation looks great in
> general.  If a change is forced on you, then I suggest you just do it in a
> way that makes your life as easy as possible.  If people don't like it,
> they can always put the effort in to do something different and then I
> expect they'll quickly come round to realising that your way is perfectly
> fine.  One way of fixing the docstring formatting would be to put
> instructions and a couple of examples somewhere handy and ask people to fix
> problems when they encounter them as they read the docs.  That should be a
> small effort from each person that would hopefully fix the important ones
> quickly in a self-prioritising manner.
> Thanks for putting the time into this,
> Dave
>
>
> On Wed, May 2, 2018 at 8:40 AM, Greg Landrum 
> wrote:
>
>> Dear all,
>>
>> Just over a year ago I asked for feedback on a new documentation format
>> for the RDKit python API: https://www.mail-archive.
>> com/rdkit-discuss@lists.sourceforge.net/msg06688.html
>> Some useful feedback came in on that thread (thanks to those who replied
>> there and in private email), but I ran out of time/motivation to spend time
>> on this.
>>
>> With my motivation recharged thanks to the "fun" of using epydoc to
>> document the last release, I revisited the topic this weekend and actually
>> made some progress.[1] I'd like to gather a second round of feedback on
>> that.
>>
>> The documentation is here:
>> http://rdkit.org/docs_temp/index.html
>> The API docs (which are where the biggest changes are) are here:
>> http://rdkit.org/docs_temp/api-docs.html
>>
>> To address some of the things raised last time:
>> - This really isn't optional. It's been more than a decade since epydoc
>> was updated and it requires python 2.7.
>> - My previous attempt to auto-generate docs used pdoc (
>> https://github.com/BurntSushi/pdoc). That project also seems to have
>> died, so it's not really an option.
>> - Based upon the two factors above I decided to use the autodoc
>> functionality that's part of Sphinx. It's not perfect, but it's supported
>> (and seems likely to continue to be so since it's part of Sphinx)
>>
>> - The docs now have a search box
>>
>> - We've lost the overview (list of classes/functions/etc) that epydoc
>> provides. There likely is a way to do this with sphinx, but I haven't
>> managed to get it to work yet
>>
>> - Formatting: Some of the docstrings end up looking pretty good, others
>> are awful. Here's a module that demonstrates both sides of the coin:
>> http://rdkit.org/docs_temp/source/rdkit.Chem.AtomPairs.Pairs
>> .html#module-rdkit.Chem.AtomPairs.Pairs
>> Fixing this is "just" a matter of editing the doc strings. This is
>> reasonably mechanical, but unfortunately not automatable, work. It should
>> be done, but in the meantime the broken docstrings aren't completely
>> useless.
>>
>> There's also a github issue for this:
>> https://github.com/rdkit/rdkit/issues/1656
>> I'm doing the work on this branch:
>> https://github.com/greglandrum/rdkit/tree/dev/usinx_sphinx_autodoc
>>
>> -greg
>> [1] Remember how I said I was going to take a short break and do
>> something fun? This isn't that.
>>
>>
>> 
>> --
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> ___
>> Rdkit-discuss mailing list
>> Rdkit-discuss@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/rdkit-discuss
>>
>>
>
>
> --
> David Cosgrove
> Freelance computational chemistry and chemoinformatics developer
> http://cozchemix.co.uk
>
>
> 
> --
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> ___
> Rdkit-discuss mailing list
> Rdkit-discuss@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/rdkit-discuss
>
>
--
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot___
Rdkit-discuss mailing list
Rdkit-discuss@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/rdkit-discuss

Re: [Rdkit-discuss] another request for feedback on a new python API documentation format

[David Cosgrove]

Hi Greg,
After a quick poke about, I think the new documentation looks great in
general.  If a change is forced on you, then I suggest you just do it in a
way that makes your life as easy as possible.  If people don't like it,
they can always put the effort in to do something different and then I
expect they'll quickly come round to realising that your way is perfectly
fine.  One way of fixing the docstring formatting would be to put
instructions and a couple of examples somewhere handy and ask people to fix
problems when they encounter them as they read the docs.  That should be a
small effort from each person that would hopefully fix the important ones
quickly in a self-prioritising manner.
Thanks for putting the time into this,
Dave


On Wed, May 2, 2018 at 8:40 AM, Greg Landrum  wrote:

> Dear all,
>
> Just over a year ago I asked for feedback on a new documentation format
> for the RDKit python API: https://www.mail-archive.
> com/rdkit-discuss@lists.sourceforge.net/msg06688.html
> Some useful feedback came in on that thread (thanks to those who replied
> there and in private email), but I ran out of time/motivation to spend time
> on this.
>
> With my motivation recharged thanks to the "fun" of using epydoc to
> document the last release, I revisited the topic this weekend and actually
> made some progress.[1] I'd like to gather a second round of feedback on
> that.
>
> The documentation is here:
> http://rdkit.org/docs_temp/index.html
> The API docs (which are where the biggest changes are) are here:
> http://rdkit.org/docs_temp/api-docs.html
>
> To address some of the things raised last time:
> - This really isn't optional. It's been more than a decade since epydoc
> was updated and it requires python 2.7.
> - My previous attempt to auto-generate docs used pdoc (https://github.com/
> BurntSushi/pdoc). That project also seems to have died, so it's not
> really an option.
> - Based upon the two factors above I decided to use the autodoc
> functionality that's part of Sphinx. It's not perfect, but it's supported
> (and seems likely to continue to be so since it's part of Sphinx)
>
> - The docs now have a search box
>
> - We've lost the overview (list of classes/functions/etc) that epydoc
> provides. There likely is a way to do this with sphinx, but I haven't
> managed to get it to work yet
>
> - Formatting: Some of the docstrings end up looking pretty good, others
> are awful. Here's a module that demonstrates both sides of the coin:
> http://rdkit.org/docs_temp/source/rdkit.Chem.AtomPairs.
> Pairs.html#module-rdkit.Chem.AtomPairs.Pairs
> Fixing this is "just" a matter of editing the doc strings. This is
> reasonably mechanical, but unfortunately not automatable, work. It should
> be done, but in the meantime the broken docstrings aren't completely
> useless.
>
> There's also a github issue for this:
> https://github.com/rdkit/rdkit/issues/1656
> I'm doing the work on this branch:
> https://github.com/greglandrum/rdkit/tree/dev/usinx_sphinx_autodoc
>
> -greg
> [1] Remember how I said I was going to take a short break and do something
> fun? This isn't that.
>
>
> 
> --
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> ___
> Rdkit-discuss mailing list
> Rdkit-discuss@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/rdkit-discuss
>
>


-- 
David Cosgrove
Freelance computational chemistry and chemoinformatics developer
http://cozchemix.co.uk
--
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot___
Rdkit-discuss mailing list
Rdkit-discuss@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/rdkit-discuss

[Rdkit-discuss] another request for feedback on a new python API documentation format

[Greg Landrum]

Dear all,

Just over a year ago I asked for feedback on a new documentation format for
the RDKit python API:
https://www.mail-archive.com/rdkit-discuss@lists.sourceforge.net/msg06688.html
Some useful feedback came in on that thread (thanks to those who replied
there and in private email), but I ran out of time/motivation to spend time
on this.

With my motivation recharged thanks to the "fun" of using epydoc to
document the last release, I revisited the topic this weekend and actually
made some progress.[1] I'd like to gather a second round of feedback on
that.

The documentation is here:
http://rdkit.org/docs_temp/index.html
The API docs (which are where the biggest changes are) are here:
http://rdkit.org/docs_temp/api-docs.html

To address some of the things raised last time:
- This really isn't optional. It's been more than a decade since epydoc was
updated and it requires python 2.7.
- My previous attempt to auto-generate docs used pdoc (
https://github.com/BurntSushi/pdoc). That project also seems to have died,
so it's not really an option.
- Based upon the two factors above I decided to use the autodoc
functionality that's part of Sphinx. It's not perfect, but it's supported
(and seems likely to continue to be so since it's part of Sphinx)

- The docs now have a search box

- We've lost the overview (list of classes/functions/etc) that epydoc
provides. There likely is a way to do this with sphinx, but I haven't
managed to get it to work yet

- Formatting: Some of the docstrings end up looking pretty good, others are
awful. Here's a module that demonstrates both sides of the coin:
http://rdkit.org/docs_temp/source/rdkit.Chem.AtomPairs.Pairs.html#module-rdkit.Chem.AtomPairs.Pairs
Fixing this is "just" a matter of editing the doc strings. This is
reasonably mechanical, but unfortunately not automatable, work. It should
be done, but in the meantime the broken docstrings aren't completely
useless.

There's also a github issue for this:
https://github.com/rdkit/rdkit/issues/1656
I'm doing the work on this branch:
https://github.com/greglandrum/rdkit/tree/dev/usinx_sphinx_autodoc

-greg
[1] Remember how I said I was going to take a short break and do something
fun? This isn't that.
--
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot___
Rdkit-discuss mailing list
Rdkit-discuss@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/rdkit-discuss