autodoc members for module vs. class
Elaine Angelino
i really like using autodocs in sphinx to complement handwritten "tutorial-style" docs
when i use ":members:" to include the members of an automodule, the members (e.g. functions inside of the module) appear in the documentation in the same order in which they appear in the module, e.g. when i write:
.. automodule:: module.name
:members:
however, when i use ":members:" to include the members of an autoclass, the members (e.g. class methods) appear in alphabetical order, e.g. when i write:
.. autoclass:: class.name
:members:
i would really like to have the class methods automatically appear in the same order in which they appear in the class. this can be useful when the class methods are grouped conceptually.
is there a configuration setting i am not using properly? something else?
thanks for any help!
elaine
elaine
understand the following difference about using autodocs to include
members of an automodule vs. an autoclass:
the autodocs for the members (e.g. functions) of an automodule
correspond to their order in the code of that module, while the
autodocs for the members of an autoclass (e.g. methods) appear in
alphabetical order.
i would like to have the members of an autoclass appear in the same
order as they are in the code of that class. can i do this
automatically? e.g. when using:
.. autoclass:: class.name
:members:
please let me know if i am being unclear, thanks a bunch!
elaine
Georg Brandl
> hi -- i am just resending my post from the other day, does anybody
> understand the following difference about using autodocs to include
> members of an automodule vs. an autoclass:
>
> the autodocs for the members (e.g. functions) of an automodule
> correspond to their order in the code of that module, while the
> autodocs for the members of an autoclass (e.g. methods) appear in
> alphabetical order.
>
> i would like to have the members of an autoclass appear in the same
> order as they are in the code of that class. can i do this
> automatically? e.g. when using:
>
> .. autoclass:: class.name
> :members:
>
> please let me know if i am being unclear, thanks a bunch!
Hi,
I think that the first case (members in modules appearing in the
source order) was just a coincidence. Members are always sorted
in alphabetical order (or, when selected, ordered by type first),
because Python introspection doesn't let you find out the source
order -- all members are in a dictionary, whether in a module or
in a class.
(Now that we have the ModuleAnalyzer, ordering by source order
would be possible, but is not implemented.)
Georg
Elaine Angelino
i thought it was just by chance too. however, below is an example list of functions from one module that appeared in the (following) order, same as in the module itself.
they are definitely not in alphabetical order!
perhaps i do not understand what is meant by ordering by type?
thanks your help,
elaine
---------
loadSV
saveSV
loadbinary
savebinary
loadHSV
saveHSV
savecolumns
loadHSVlist
appendHSV
appendcolumns
loadrowdata
typeinfer
infercoloring
inferdelimiter
Georg Brandl
> hi georg -- thanks for your response!
>
> i thought it was just by chance too. however, below is an example list
> of functions from one module that appeared in the (following) order,
> same as in the module itself.
>
> they are definitely not in alphabetical order!
Can't object there... I forgot about another feature, which is that
__all__ is respected if present, and members are documented in the
order given by __all__. I hope this is the case for you, otherwise
it's a mystery :)
> perhaps i do not understand what is meant by ordering by type?
You can optionally order by member type, e.g. functions first, then
attributes.
cheers,
Georg
Denis
Adding this snippet to conf.py works for me - makes the methods of the
class appear in the same order as in the code:
from sphinx.ext import autodoc
from sphinx.ext.autodoc import ClassDocumenter
class MyClassDocumenter(ClassDocumenter):
def get_object_members(self, want_all):
members_check_module, members = super(MyClassDocumenter,
self).get_object_members(want_all)
def key((name, obj)):
try:
return obj.im_func.func_code.co_firstlineno
except AttributeError:
return 0
members.sort(key=key)
return members_check_module, members
autodoc.ClassDocumenter = MyClassDocumenter
This may not work in your case. In particular, it won't work if you
set autodoc_member_order to 'groupwise'.
Would be nice if sphinx had an option to do this without hacking.
Georg Brandl
Hash: SHA1
Denis schrieb:
> Hi,
>
> Adding this snippet to conf.py works for me - makes the methods of the
> class appear in the same order as in the code:
>
> from sphinx.ext import autodoc
> from sphinx.ext.autodoc import ClassDocumenter
>
> class MyClassDocumenter(ClassDocumenter):
>
> def get_object_members(self, want_all):
> members_check_module, members = super(MyClassDocumenter,
> self).get_object_members(want_all)
> def key((name, obj)):
> try:
> return obj.im_func.func_code.co_firstlineno
> except AttributeError:
> return 0
> members.sort(key=key)
> return members_check_module, members
>
> autodoc.ClassDocumenter = MyClassDocumenter
>
> This may not work in your case. In particular, it won't work if you
> set autodoc_member_order to 'groupwise'.
>
> Would be nice if sphinx had an option to do this without hacking.
It's a nice hack. It doesn't work with inherited methods, though,
it'll have to be grouped by co_filename somehow (but finding out
which one to place first is tricky).
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.11 (GNU/Linux)
iEYEARECAAYFAkr3GpkACgkQN9GcIYhpnLDSIgCeJcj+Hz5CjVMuB0YR7LUtHul3
uiIAnjxFUS+waDE8RuAW0x1PohxBVrC0
=J/Ha
-----END PGP SIGNATURE-----