Override default signature of __getitem__ in autodoc for sphinx
up vote
1
down vote
favorite
I have a class Foo that supports subscripting, so if foo is an instance of Foo, foo[12] will find the 12th one. Foo is defined something like this:
class Foo:
def __getitem__(self, i):
"""Get the ith element of self."""
....
The sphinx rst file looks something like this:
.. autoclass:: Foo
:members: __getitem__, ...
When sphinx builds the documentation, Foo's subscript-implementing __getitem__ member function is documented as:
__getitem__(i)
Get the ith element of the Foo.
But that function signature will be confusing to a reader of the documentation who does not know about Python dunder functions, and who does not know that subscripting brackets are defined with __getitem__. It would be better to have __getitem__ documented like this:
foo[i]
Get the ith element of the Foo foo.
Is there a way to override the member function signature with foo[i], which does not look like a signature at all?
python python-sphinx autodoc
asked Nov 19 at 12:30
David Bridgeland
1661315
add a comment |
up vote
1
down vote
favorite
I have a class Foo that supports subscripting, so if foo is an instance of Foo, foo[12] will find the 12th one. Foo is defined something like this:
class Foo:
def __getitem__(self, i):
"""Get the ith element of self."""
....
The sphinx rst file looks something like this:
.. autoclass:: Foo
:members: __getitem__, ...
When sphinx builds the documentation, Foo's subscript-implementing __getitem__ member function is documented as:
__getitem__(i)
Get the ith element of the Foo.
But that function signature will be confusing to a reader of the documentation who does not know about Python dunder functions, and who does not know that subscripting brackets are defined with __getitem__. It would be better to have __getitem__ documented like this:
foo[i]
Get the ith element of the Foo foo.
Is there a way to override the member function signature with foo[i], which does not look like a signature at all?
python python-sphinx autodoc
asked Nov 19 at 12:30
David Bridgeland
1661315
I'm not sure you're doing this right. Have you tried adding__getitem__with:special-members:as described here?
– Nearoo
Nov 19 at 13:55
1
The behavior of:special-members:is curious. When:members:is used without a explicit list of members,:special-members:is needed to specify dunders. But when:members:has an explicit list (e.g.:members: foo, bar),:special-members:has no effect at all. It seems that an explicit list of members requires any dunders to be included in the list. (In my case that is not unreasonable, as I have only a few members that I want documented, and only two dunders.) And in any case,:special-members:seems only about whether a dunder is documented, not how the signature looks.
– David Bridgeland
Nov 20 at 11:41
1
The buggy behaviour ofspecial-memberswas fixed in Sphinx 1.8. See github.com/sphinx-doc/sphinx/issues/2401.
– mzjn
Nov 20 at 19:21
Related proposal: github.com/sphinx-doc/sphinx/issues/5702
– mzjn
yesterday
add a comment |
up vote
1
down vote
favorite
up vote
1
down vote
favorite
I have a class Foo that supports subscripting, so if foo is an instance of Foo, foo[12] will find the 12th one. Foo is defined something like this:
class Foo:
def __getitem__(self, i):
"""Get the ith element of self."""
....
The sphinx rst file looks something like this:
.. autoclass:: Foo
:members: __getitem__, ...
When sphinx builds the documentation, Foo's subscript-implementing __getitem__ member function is documented as:
__getitem__(i)
Get the ith element of the Foo.
But that function signature will be confusing to a reader of the documentation who does not know about Python dunder functions, and who does not know that subscripting brackets are defined with __getitem__. It would be better to have __getitem__ documented like this:
foo[i]
Get the ith element of the Foo foo.
Is there a way to override the member function signature with foo[i], which does not look like a signature at all?
python python-sphinx autodoc
asked Nov 19 at 12:30
David Bridgeland
1661315
I have a class Foo that supports subscripting, so if foo is an instance of Foo, foo[12] will find the 12th one. Foo is defined something like this:
class Foo:
def __getitem__(self, i):
"""Get the ith element of self."""
....
The sphinx rst file looks something like this:
.. autoclass:: Foo
:members: __getitem__, ...
When sphinx builds the documentation, Foo's subscript-implementing __getitem__ member function is documented as:
__getitem__(i)
Get the ith element of the Foo.
But that function signature will be confusing to a reader of the documentation who does not know about Python dunder functions, and who does not know that subscripting brackets are defined with __getitem__. It would be better to have __getitem__ documented like this:
foo[i]
Get the ith element of the Foo foo.
Is there a way to override the member function signature with foo[i], which does not look like a signature at all?
python python-sphinx autodoc
python python-sphinx autodoc
asked Nov 19 at 12:30
David Bridgeland
1661315
asked Nov 19 at 12:30
David Bridgeland
1661315
edited Nov 20 at 11:43
asked Nov 19 at 12:30
David Bridgeland
1661315
asked Nov 19 at 12:30
David Bridgeland
1661315
asked Nov 19 at 12:30
David Bridgeland
1661315
1661315
I'm not sure you're doing this right. Have you tried adding__getitem__with:special-members:as described here?
– Nearoo
Nov 19 at 13:55
1
The behavior of:special-members:is curious. When:members:is used without a explicit list of members,:special-members:is needed to specify dunders. But when:members:has an explicit list (e.g.:members: foo, bar),:special-members:has no effect at all. It seems that an explicit list of members requires any dunders to be included in the list. (In my case that is not unreasonable, as I have only a few members that I want documented, and only two dunders.) And in any case,:special-members:seems only about whether a dunder is documented, not how the signature looks.
– David Bridgeland
Nov 20 at 11:41
1
The buggy behaviour ofspecial-memberswas fixed in Sphinx 1.8. See github.com/sphinx-doc/sphinx/issues/2401.
– mzjn
Nov 20 at 19:21
Related proposal: github.com/sphinx-doc/sphinx/issues/5702
– mzjn
yesterday
add a comment |
I'm not sure you're doing this right. Have you tried adding__getitem__with:special-members:as described here?
– Nearoo
Nov 19 at 13:55
1
The behavior of:special-members:is curious. When:members:is used without a explicit list of members,:special-members:is needed to specify dunders. But when:members:has an explicit list (e.g.:members: foo, bar),:special-members:has no effect at all. It seems that an explicit list of members requires any dunders to be included in the list. (In my case that is not unreasonable, as I have only a few members that I want documented, and only two dunders.) And in any case,:special-members:seems only about whether a dunder is documented, not how the signature looks.
– David Bridgeland
Nov 20 at 11:41
1
The buggy behaviour ofspecial-memberswas fixed in Sphinx 1.8. See github.com/sphinx-doc/sphinx/issues/2401.
– mzjn
Nov 20 at 19:21
Related proposal: github.com/sphinx-doc/sphinx/issues/5702
– mzjn
yesterday
I'm not sure you're doing this right. Have you tried adding
__getitem__ with :special-members: as described here?– Nearoo
Nov 19 at 13:55
I'm not sure you're doing this right. Have you tried adding
__getitem__ with :special-members: as described here?– Nearoo
Nov 19 at 13:55
1
1
The behavior of
:special-members: is curious. When :members: is used without a explicit list of members, :special-members: is needed to specify dunders. But when :members: has an explicit list (e.g. :members: foo, bar), :special-members: has no effect at all. It seems that an explicit list of members requires any dunders to be included in the list. (In my case that is not unreasonable, as I have only a few members that I want documented, and only two dunders.) And in any case, :special-members: seems only about whether a dunder is documented, not how the signature looks.– David Bridgeland
Nov 20 at 11:41
The behavior of
:special-members: is curious. When :members: is used without a explicit list of members, :special-members: is needed to specify dunders. But when :members: has an explicit list (e.g. :members: foo, bar), :special-members: has no effect at all. It seems that an explicit list of members requires any dunders to be included in the list. (In my case that is not unreasonable, as I have only a few members that I want documented, and only two dunders.) And in any case, :special-members: seems only about whether a dunder is documented, not how the signature looks.– David Bridgeland
Nov 20 at 11:41
1
1
The buggy behaviour of
special-members was fixed in Sphinx 1.8. See github.com/sphinx-doc/sphinx/issues/2401.– mzjn
Nov 20 at 19:21
The buggy behaviour of
special-members was fixed in Sphinx 1.8. See github.com/sphinx-doc/sphinx/issues/2401.– mzjn
Nov 20 at 19:21
Related proposal: github.com/sphinx-doc/sphinx/issues/5702
– mzjn
yesterday
Related proposal: github.com/sphinx-doc/sphinx/issues/5702
– mzjn
yesterday
add a comment |
active
oldest
votes
active
oldest
votes
active
oldest
votes
active
oldest
votes
active
oldest
votes
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Some of your past answers have not been well-received, and you're in danger of being blocked from answering.
Please pay close attention to the following guidance:
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53374699%2foverride-default-signature-of-getitem-in-autodoc-for-sphinx%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
I'm not sure you're doing this right. Have you tried adding
__getitem__with:special-members:as described here?– Nearoo
Nov 19 at 13:55
1
The behavior of
:special-members:is curious. When:members:is used without a explicit list of members,:special-members:is needed to specify dunders. But when:members:has an explicit list (e.g.:members: foo, bar),:special-members:has no effect at all. It seems that an explicit list of members requires any dunders to be included in the list. (In my case that is not unreasonable, as I have only a few members that I want documented, and only two dunders.) And in any case,:special-members:seems only about whether a dunder is documented, not how the signature looks.– David Bridgeland
Nov 20 at 11:41
1
The buggy behaviour of
special-memberswas fixed in Sphinx 1.8. See github.com/sphinx-doc/sphinx/issues/2401.– mzjn
Nov 20 at 19:21
Related proposal: github.com/sphinx-doc/sphinx/issues/5702
– mzjn
yesterday