Re: [Rdkit-discuss] looking for feedback on new python API documentation format

[Rocco Moretti]

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

[Juuso Lehtivarjo]

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

[Peter S. Shenkin]

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 

[Rdkit-discuss] looking for feedback on new python API documentation format

[Greg Landrum]

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