One potential issue with the new pdoc documentation is how it handles (or
rather doesn't) namespace transclusions.
For example, say you were looking for documentation on
rdkit.Chem.MolFromMolFile. If you go to the rdkit.Chem page for pdoc (
http://rdkit.org/docs_temp/Chem/index.html) MolFromMolFile is not listed
anywhere on that page.
In contrast, for the old version (
http://rdkit.org/docs/api/rdkit.Chem-module.html) a link to the
MolFromMolFile documentation is there in the "Imports*:*" section. It's not
great, stuck in a massive block like that, but it's definitely ctrl-F-able
in your browser.
I think this is a potentially serious issue given how RDKit is typically
used. As most usage of objects typically goes through Chem or AllChem,
rather than the specific module that they originate from, most of the time
there will be no real way for users to find that function starting from the
top page of the new documentation. They might get to the Chem or AllChem
page and then hit a dead end. And as Juuso points out, there also doesn't
seem to be a flat list or a search box, so what you're left with is going
to Google.
Regards,
-Rocco
On Tue, Mar 28, 2017 at 11:10 PM, 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
