Re: [Rdkit-discuss] looking for feedback on new python API documentation format
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 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
Re: [Rdkit-discuss] looking for feedback on new python API documentation format
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 " usually gets me there fastest anyway, but still...) Best, Juuso On Wed, Mar 29, 2017 at 7:10 AM, Greg Landrum 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
Re: [Rdkit-discuss] looking for feedback on new python API documentation format
Hi, Greg, Here are my comments. - Formatting - pdoc at a glance is certainly more handsome than epydoc - To my eye, there is a huge amount of wasted space in the pdoc documentation. - The line spacing is hugely disproportional to the font size - Maybe this could be adjusted by font and line-spacing options - But it's a problem because so little is shown on a page. - Documentation hierarchy - The ePydoc documentation requires you to drill down an extra level: - epydoc: http://rdkit.org/docs/api/rdkit.Chem.AllChem-module.html - At the top of this link, you see all the function names together, but you have to drill down to see the details of any particular function - pdoc: http://rdkit.org/docs_temp/Chem/AllChem.m.html - You see each function with its full description at the module level. - I personally prefer epydoc here, because I usually want to see a list of (functions, classes, whatever) at the top level to figure out what I want to drill down to. - I'm just a "forest" kind of guy, and would like to pick my tree before I see all its gory details. - I accept that this might just be personal taste. - Code Examples - ePydoc shows the code examples correctly; pdoc does not. - epydoc: Drilling down, http://rdkit.org/docs/api/rdkit.Chem.AllChem-module.html#AssignBondOrdersFromTemplate, consider these lines from the example code: - >>> from rdkit.Chem import AllChem >>> template = AllChem.MolFromSmiles("CN1C(=NC(C1=O)(c2c2)c3c3)N") >>> mol = AllChem.MolFromPDBFile(os.path.join(RDConfig.RDCodeDir, 'Chem', 'test_data', '4DJU_lig.pdb')) >>> len([1 for b in template.GetBonds() if b.GetBondTypeAsDouble() == 1.0]) 8 >>> len([1 for b in mol.GetBonds() if b.GetBondTypeAsDouble() == 1.0]) 22 - This is very legible. - pdoc: On the same link we were at before, http://rdkit.org/docs_temp/Chem/AllChem.m.html, look at the same code example: - import os from rdkit.Chem import AllChem template = AllChem.MolFromSmiles("CN1C(=NC(C1=O)(c2c2)c3c3)N") mol = AllChem.MolFromPDBFile(os.path.join(RDConfig.RDCodeDir, 'Chem', 'test_data', '4DJU_lig.pdb')) len([1 for b in template.GetBonds() if b.GetBondTypeAsDouble() == 1.0]) 8 len([1 for b in mol.GetBonds() if b.GetBondTypeAsDouble() == 1.0]) 22 - Line breaks are not observed; prompts are not observed; responses don't appear on their new lines, etc. This is illegible. - (There is an additional import statement here. That's not a problem, but note that the second import is concatenated on the same line.) - This is unacceptable, but perhaps it can be fixed. - Summary - The fact that epydoc is no longer supported weighs heavily against it - If the current examples are as good as pdoc can do, it is unsatisfactory, especially because of poor code printing; but there could be other tigers lurking in the woods. - I feel the wasted space in pdoc due to the huge line spacing is pretty bad. - pdoc would be worth another look if these issues can be fixed, but the a second look would be required, because there could be other problems that are obscured by the above. - I like Sphynx, and it would be great if it could be made to work with RDKit. (With Google style docstrings!) - Either way, I wish the RDKit documentation included the types of function arguments and return values, which both Sphynx and epydoc have provision for. - I assume pdoc has provision for this, too, but if not, that's a big negative. - Adding documentation of arguments and return values would be a big job at this point and isn't part of the current effort; but I feel it's important to pick a documentation tool that would allow this to be done later. On Wed, Mar 29, 2017 at 12:10 AM, Greg Landrum 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 b