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)(c2ccccc2)c3ccccc3)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)(c2ccccc2)c3ccccc3)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 <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
