Docs

[Tony Yu]

On Mon, Oct 1, 2012 at 10:42 AM, Tony Yu <tsyu80 at gmail.com> wrote:
>
> On Mon, Oct 1, 2012 at 3:55 AM, Schönberger Johannes <
> hannesschoenberger at gmail.com> wrote:
>

<snip>


>  3. the updated API reference lists a lot of duplicates. I think, it is
>> sufficient to list "subpackage.function" and leave out the
>> "subpackage.file.function". My guess is that Sphinx 1.1.X caused this new
>> behavior.
>>
>
> Hmm, I'm not sure what could have changed this. Note that the duplicates
> appear in `doc/source/api/api.txt`, which is generated by some combination
> of apigen.py, docscrape.py, docscrape_sphinx.py, and numpydoc.py in
> `doc/tools/` and `doc/ext/`. My guess is that the problem was caused by a
> change to one of these files. I'm not sure where exactly.
>
>
> -Tony
>
>
So I tracked down this issue to apigen and submitted a PR to fix this issue:

    https://github.com/scikits-image/scikits-image/pull/334

Here's a long-winded explanation of the fix (which is a bit strange, since
all it does is delete 2 blocks of code):

Basically, apigen walks the directory tree and looks for all directories
and files that are modules, thus building a package tree. Then, it removes
the deepest level of the resulting package tree:


https://github.com/scikits-image/scikits-image/blob/master/doc/tools/apigen.py#L430


In our case, removing the deepest level meant that it didn't document `
skimage.filter.edges.py` as it's own module, which was perfect since the
public functions were imported into `skimage.filter`.

Now, the problem is that apigen looks for the deepest level of the entire
tree and just removes that level. So if we add a subpackage that has an
extra level---e.g., `skimage.viewer.plugin.lineprofile.py`---then `edges`
won't get stripped when removing the deepest level (since that level is now
higher---or lower, depending on how you view the tree ;)

If we wanted to follow the same logic as the original code, then we can
just strip the leaf modules from the package tree. The pull request I
submitted takes a different approach: Don't try to document python files,
just document subpackages. This solution may not be robust, but I'm not
really sure ignoring all the leaf modules would be either.

-Tony
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scikit-image/attachments/20121002/2197a7e2/attachment.html>