Waiting for review: Add get_members function to apidoc templates (better_apidoc backport) #6768

goerz · 2019-10-24T23:00:02Z

This make a get_members function available to the module.rst_t and package.rst_t templates used by apidoc. This function allows to obtain the members of the current module or package in various forms and filtered by "type" (exception, class, function, data).

Building upon the recent addition of templating to apidoc in v2.2, this is a backport of https://github.com/goerz/better-apidoc

The original motivation for better-apidoc was that I find apidoc's default template to be extremely hard to navigate for modules with a lot of members, see #3545. I strongly prefer to have a summary/table of contents at the beginning of each module's documentation that lists all the members of the module, and specifies which members are available through __all__

Examples of projects that use such a format (currently using better-apidoc, but possible with the features added in this PR):

The get_members function provided in the PR provides an extremely powerful mechanism for custom templates. The better-apidoc project has had a long gestation period, and has undergone several iterations over the last few years. Based on my experience of using it in a number of projects like the ones linked above, I am fully confident that the functionality provided in this PR can be considered stable. I will be available to maintain this part of apidoc going forward.

Within a template, get_members can be used e.g. as follows:

{%- set members = get_members() %}
{%- set all = get_members(in_list='__all__', include_imported=True) %}
{%- set all_refs = get_members(in_list='__all__', include_imported=True, out_format='refs', known_refs='__known_refs__') -%}
{%- set exceptions = get_members(typ='exception') -%}
{%- set classes = get_members(typ='class') -%}
{%- set functions = get_members(typ='function') -%}
{%- set data = get_members(typ='data', in_list='__all__') -%}

The lists {{ members }}, {{ all }} etc. are then available in the remainder of the template.

There is extensive further documentation and examples for the templating features in apidoc, both of those added in v2.2 (which were largely undocumented) and for the get_members function added in this PR. This documentation is in the apidoc man page. The PR includes tests with full coverage of the new features.

goerz · 2019-10-24T23:05:13Z

This is a backwards-compatible feature addition on v2.2. Thus, it should go in v2.3, and I've assumed this in the documentation (cd07183#diff-4b14242400560fc0f03fe3972cc0d25bR163)

However, it appears that currently no 2.3 branch exists on Github. Thus, I've made this PR against master. If I should rebase and force-push based on another branch, please let me know.

goerz · 2019-10-24T23:08:50Z

doc/man/sphinx-apidoc.rst

+
+.. data:: basename
+
+An alias for :data:`qualname`.


This documentation matches what is currently implemented. Most likely, it's not what was intended, however. I would assume that qualname should be the fully qualified name of the module (with dots), whereas basename should only be the part after the last dot. I'll leave fixing this for another PR, though, after this is merged in.

The alternative would be for me to change the documentation of basename to "The part of the :data:qualname after the last dot". This would knowingly create my definition of a "bug" (a mismatch between documentation and behavior). If your preferred definition of "bug" is "mismatch between obvious intent and behavior", on the other hand, we can leave this for now.

I guess "qualname" came from PEP-3155's __qualname__. It is a relative path from its module. It was introduced mainly for nested classes.
https://www.python.org/dev/peps/pep-3155/

goerz · 2019-10-24T23:09:51Z

doc/man/sphinx-apidoc.rst

+Accessing module members in templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.3


This assumes the PR will be merged and released in v2.3 (the next feature release). Otherwise, this will have to be adjusted.

goerz · 2019-10-25T02:19:50Z

This is now ready for review/merging @tk0miya

The `module.rst_t` and `package.rst_t` templates used by apidoc now have a `get_members` function that allows to obtain the member of the current module or package in various forms and filtered by "type" (exception, class, function, data). This provides a powerful mechanism for writing more advanced templates. Specifically, it allows to generate structured summaries of the contents of a module, preceding the detailed `automodule` references. See https://krotov.readthedocs.io/en/stable/API/krotov.html for an example. Extensive documentation of all the templating capabilities is included in the apidoc man page in the documentation. This functionality is a backport of the "better-apidoc" package (https://github.com/goerz/better-apidoc).

goerz · 2019-12-05T15:24:35Z

@tk0miya Is there any chance you could review and merge this in the near future? I'd really love to have this in the next release, so that I can start some new projects that don't depend on my better-apidoc hack.

goerz · 2019-12-30T19:44:11Z

So it looks like 2.3 and 2.3.1 were released without this PR. Is there any interest in merging this? I'll have to modify the patch to fix the ..versionadded to whatever release this will target.

TejasAvinashShetty · 2020-01-25T08:45:49Z

eagerly waiting for this merge.

tk0miya · 2020-01-25T09:01:02Z

OMG, I must apologize you not to review this. I'll do it within a week. Please wait a moment. Thanks,

tk0miya

I'm very sorry to late response. I'd missed your ping so long

I feel this is too complex. It seems the responsibility of this function is listing attributes, filtering, formatting and so on. I can understand some people want to "hack" apidoc. And this would be helpful to them because this is very programatic. But it is hard to use and maintain to me.

I don't say this is rejected. I agreed current apidoc is poor. So improvement is still needed.

tk0miya · 2020-02-01T14:23:12Z

doc/man/sphinx-apidoc.rst

+
+.. data:: basename
+
+An alias for :data:`qualname`.


I guess "qualname" came from PEP-3155's __qualname__. It is a relative path from its module. It was introduced mainly for nested classes.
https://www.python.org/dev/peps/pep-3155/

goerz · 2020-02-01T19:32:40Z

I don't see how this can move forward then, unless you can think of any way to make it less complex while maintaining the functionality. So probably the only option for me is to maintain this as a permanent hard fork of apidoc (probably under a better name than the original better-apidoc that I used while drafting this).

EricG-Personal · 2020-02-29T01:31:11Z

I would hate to see the idea dropped of adding the functionality of better-apidoc.

gbroques · 2020-06-23T02:56:28Z

@goerz @tk0miya

Any thoughts on reaching a middle-ground, or compromise here?

Proposal 1 (Ultra Simple)

How about simplifying this to just include a members variable in the module.rst_t and package.rst_t templates that's the simple names of all qualifying members?

Proposal 2 (Less Simple)

Alternatively,

What about keeping a get_members function and removing some of the less-critcial options like out_format, include_imported, in_list, and / or include_private?

Formatting could be handled by users if they have access to members in the templates, and these changes could respect other options for including imported, private, or __all__ members such as imported-members, private-members, and ignore-module-all.

Proposal 3

?

AA-Turner · 2023-08-15T12:10:00Z

Hi Michael (@goerz) -- is this PR no longer required? I missed the reason for closing, sorry.

Thanks,
Adam

goerz · 2023-08-15T14:29:40Z

It’s not going to be merged, and I have switched from Python to Julia for all my work, so why keep it open?

goerz force-pushed the apidoctemplates branch from ef88b64 to cd07183 Compare October 24, 2019 23:01

goerz force-pushed the apidoctemplates branch from cd07183 to 61a8f38 Compare October 24, 2019 23:13

This comment was marked as outdated.

Sign in to view

goerz commented Oct 24, 2019

View reviewed changes

goerz force-pushed the apidoctemplates branch from 61a8f38 to 6ef7411 Compare October 24, 2019 23:25

goerz mentioned this pull request Oct 24, 2019

Add templating support to sphinx-apidoc #3545

Closed

goerz force-pushed the apidoctemplates branch 4 times, most recently from 947fcb8 to 65e707f Compare October 25, 2019 02:06

goerz mentioned this pull request Oct 25, 2019

"add_documenter()" is now removed from Sphinx 1.8 goerz/better-apidoc#14

Closed

goerz force-pushed the apidoctemplates branch 3 times, most recently from b8e4c92 to f5f4c97 Compare October 25, 2019 05:54

goerz force-pushed the apidoctemplates branch from f5f4c97 to 4c29279 Compare October 25, 2019 06:05

ben-spiller mentioned this pull request Nov 15, 2019

sphinx-build should auto-generate autodoc/summary rst files that can be customized using a Python callback #6829

Open

Merge branch 'master' into apidoctemplates

22fd874

goerz mentioned this pull request Dec 30, 2019

Replace better-apidoc with a future Sphinx apidoc that supports advanced templates goerz/cookiecutter-pypackage#9

Open

goerz changed the title ~~Add get_members function to apidoc templates (better_apidoc backport)~~ Waiting for review: Add get_members function to apidoc templates (better_apidoc backport) Jan 9, 2020

tk0miya reviewed Feb 1, 2020

View reviewed changes

AA-Turner added this to the some future version milestone Apr 29, 2023

goerz closed this Aug 15, 2023

github-actions bot locked as resolved and limited conversation to collaborators Sep 15, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Waiting for review: Add get_members function to apidoc templates (better_apidoc backport) #6768

Waiting for review: Add get_members function to apidoc templates (better_apidoc backport) #6768

goerz commented Oct 24, 2019 •

edited

Loading

goerz commented Oct 24, 2019

This comment was marked as outdated.

goerz Oct 24, 2019

goerz Oct 25, 2019

tk0miya Feb 1, 2020

goerz Oct 24, 2019

goerz commented Oct 25, 2019

goerz commented Dec 5, 2019

goerz commented Dec 30, 2019

TejasAvinashShetty commented Jan 25, 2020

tk0miya commented Jan 25, 2020

tk0miya left a comment

tk0miya Feb 1, 2020

goerz commented Feb 1, 2020

EricG-Personal commented Feb 29, 2020

gbroques commented Jun 23, 2020 •

edited

Loading

AA-Turner commented Aug 15, 2023

goerz commented Aug 15, 2023

Waiting for review: Add get_members function to apidoc templates (better_apidoc backport) #6768

Waiting for review: Add get_members function to apidoc templates (better_apidoc backport) #6768

Conversation

goerz commented Oct 24, 2019 • edited Loading

goerz commented Oct 24, 2019

This comment was marked as outdated.

goerz Oct 24, 2019

Choose a reason for hiding this comment

goerz Oct 25, 2019

Choose a reason for hiding this comment

tk0miya Feb 1, 2020

Choose a reason for hiding this comment

goerz Oct 24, 2019

Choose a reason for hiding this comment

goerz commented Oct 25, 2019

goerz commented Dec 5, 2019

goerz commented Dec 30, 2019

TejasAvinashShetty commented Jan 25, 2020

tk0miya commented Jan 25, 2020

tk0miya left a comment

Choose a reason for hiding this comment

tk0miya Feb 1, 2020

Choose a reason for hiding this comment

goerz commented Feb 1, 2020

EricG-Personal commented Feb 29, 2020

gbroques commented Jun 23, 2020 • edited Loading

Proposal 1 (Ultra Simple)

Proposal 2 (Less Simple)

Proposal 3

AA-Turner commented Aug 15, 2023

goerz commented Aug 15, 2023

goerz commented Oct 24, 2019 •

edited

Loading

gbroques commented Jun 23, 2020 •

edited

Loading