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 <greg.land...@gmail.com> 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
