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

Reply via email to