Hi Greg, Here's my user case: usually I want to find out the details of a certain class/function I already know of, but I may not have a clue to which module that class/function belongs to. This is where the alphabetical index of epydoc is often quite handy. Of course a proper search within the doc site, such as in sphinx, would be perfect. It seems that pdoc doesn't offer either of those? (OK, to be honest, plain googling of "rdkit <function>" usually gets me there fastest anyway, but still...)
Best, Juuso On Wed, Mar 29, 2017 at 7:10 AM, Greg Landrum <greg.land...@gmail.com> wrote: > Dear all, > > TL;DR > I'd like to switch to a new system for generating the RDKit Python API > documentation and I'd like some feedback. > > Please take a look at this possible API documentation format: > http://rdkit.org/docs_temp/ > and let me know if it looks like it looks as useful as the old API doc > format: > http://rdkit.org/docs/api/index.html > > > More context: > The current documentation (http://rdkit.org/docs/api/index.html) is > generated using epydoc. It's functional, though quite "old school" looking. > The problem is that epydoc is no longer supported (and hasn't been for quite > a while) and does not support python3 at all. so I would like to move off of > it. > > In theory the API docs can be generated with Sphinx, which is what I use for > the rest of the documentation, but I haven't been able to get it working > correctly with the rdkit.[1] > > I've done a bit of looking around and it seems like the closest thing to a > replacement for epydoc is pdoc (https://github.com/BurntSushi/pdoc). This > was easy enough to figure out (despite the page hosting its own docs being > down) and generates documentation for the RDKit API without too much > trouble. The results (http://rdkit.org/docs_temp/) are certainly more modern > looking that what epydoc generates and seem to be equally useful. > > If anyone has suggestions for other things that I should look at, I would be > happy to hear them. Constraints there: > - The system must support extension modules > - It needs to discovery the things to be documented automatically (i.e. I > should only have to tell it to document the rdkit module and it figures out > the rest). > - Anything that requires changing the actual documentation itself is not a > viable option. > - It has to generate HTML > > > Thanks, > -greg > [1] The specific problem there is that it seems that sphinx-apidoc does not > pick up extension modules, which renders the RDKit API docs rather sparse > and useless. I'd love to find out that this was user error though. > > ------------------------------------------------------------------------------ > 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
