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
[email protected]
2018-05-02 11:17 GMT+02:00 David Cosgrove <[email protected]>:
> 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 <[email protected]>
> 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/[email protected]/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
>> [email protected]
>> 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
> [email protected]
> 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
[email protected]
https://lists.sourceforge.net/lists/listinfo/rdkit-discuss
