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
