search

Chilipp / autodocsumm

Extending your autodoc API docs with a summary
Apache License 2.0
48 stars 14 forks source link

Added options for summary only #18

Closed Chilipp closed 5 years ago

Chilipp commented 5 years ago

This PR adds the autosummary-members, autosummary-undoc-members, etc. options to create the summary tables without the need of the real documentation (see feature request at https://github.com/Chilipp/autodocsumm/issues/15)

Closes https://github.com/Chilipp/autodocsumm/issues/15

@maeddlae: Would you take a look at it? The idea is to have additional options that only affect the summary tables.

.. autoclass:: module.Class
    :autosummary:
    :autosummary-members:
    :no-members:

should do exactly what you want. It also works with all other options listed in the autodocsumm.member_options attribute (see https://github.com/Chilipp/autodocsumm/blob/12139d6fa335c85bf5f4cc63e87fc6a8c8ce4163/autodocsumm/__init__.py#L63-L68)

maeddlae commented 5 years ago

Works well:-)

But there is one point I forgot to consider: I would like to generate an overview .rst per class (this makes my generator quite good) which contains the class apidoc and an autodocsummary. This is what you implemented and it works exactly as it should. The linked methods in the summary must be documented somewhere else. So I generate a second, full-scaled .rst with the class and all its methods. The summary methods of the overview .rst then link to this full-scaled .rst. So far so good. In order to remove the sphinx warnings caused by two equal classes in the doc I add the ":noindex:" property to the first one (the one that holds the summary only). The links then work as expected. But all links to another class (e.g. by showing inheritance in class apidoc) then refer to the full-scaled and not to the overview! This is somehow ugly, but I think we can't solve this problem easily. It is likely caused by Sphinx internal link mechanism.

Finally, your changes work perfectly. Thank you very much!

Chilipp commented 5 years ago

Great! Glad to hear that @maeddlae, thanks 😄 Yes, we should include this in the documentation of the feature.

I did this here, would you mind having a look at it and provide your feedback? I see that the paragraph handling needs to be improved for this, so we should fix https://github.com/Chilipp/autodocsumm/issues/14 before the next release.

maeddlae commented 5 years ago

Checked the documentation: looks good

Chilipp commented 5 years ago

All right, thanks 👍