Is it possible do disable the complete autosummary when using autodoc?
I've got a class derived from a Python standard library class, which has many public methods. My custom class should work as a wrapper, directly providing methods to communicate with my device using its protocol.
Therefore I only want to include a few selected inherited methods in the autosummary table.
.. autoclass:: my_module.MyClass
:members:
:show-inheritance:
.. autosummary::
my_method
another_method
The ..autosummary:: block does exactly what I desire, but ..autoclass:: automatically creates a full methods table. Is there a way to disable this feature?
Edit (clarification)
Using the autosummary directive directly, I'm able to produce a method table containing only my_method and another_method:
.. autosummary::
my_method
another_method
However, when using autoclass or automodule without a following autosummary directive, I still get a method table looking exactly like the one created by the autosummary block above, only with all methods described:
.. autoclass:: my_module.MyClass
:members:
:show-inheritance
Edit 2
The "complete" autosummary table is being generated by numpydoc.
The "problem" was not inside autodoc or autosummary.
Though not mentioned in the question I'm using numpydoc, which was generating the additional autosummary table.
As described in numpydoc's documentation, this feature can be disabled by adding numpydoc_show_inherited_class_members = False to the sphinx conf.py.
You can remove the :members: tag, or include a comma separated list after :members: of only the methods you want to include in your documentation.
Related
Problem
To fully use the autodoc potential, I want to document my code with something like:
.. automodule :: mymodule
However, mymodule is made of a class that has it's own documenter. One of my project's dependencies created a subclass of sphinx.ext.autodoc.ClassDocumenter that documents a class it provides. My mymodule is made up of classes derived from that base one. The custom documenter has an option I want to use, how do I provide it while using automodule?
Alternative formulation
Another case that I think is the same problem:
.. automodule :: mymodule
.. automodule :: myothermodule
These two modules are made of classes that will be documented with autoclass. I want to activate the ":inherited-members:" option for classes of the first mymodule but not on the ones of myothermodule. Is this possible?
I have a comment in my python module that documents several classes that follow, e.g.
###
# Classes for agents: patients and clinicians
###
class EngagementLadder(transitions.Machine):
"""The state machine for agent states.
In fact there are several such multi-class comments. Each serves to break up the file, together organizing it into related sections.
I would like to see those comments in the generated documentation, perhaps as headers. How to do that?
Note that my question is similar to In Sphinx, how to include docstrings/comments located in a module, but outside of class and methods, but the answer that worked for him---putting it in the module docstring---will not work for me as I want these comments further down the file.
One method of achieving this is to use dummy variables
I.e. The below will add a section heading
SECTION_A = "SECTION A"
"""Section A contains some useful stuff about my project...
It can span multiple lines...
"""
def foo():
"""Description of foo"""
pass
#: Section B contains some useful stuff about my project...
#: It can span multiple lines
SECTION_B = "SECTION B"
def bar():
"""Description of foo"""
pass
Documentation here: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute
Each of our page objects has around 80-100 PageObject elements defined. This is a byproduct of a very data centric application and I don't see that changing any time soon. We have many text fields, select lists, buttons, and menus. I want to clean up these somehow and put them somewhere, but the things I've thought about don't seem very clean.
Ideas:
Move elements for each PageObject into a corresponding module and include that module into a single PageObject only
create a YAML config file, with the mapping of element_type => element_name => element_id and then call the corresponding element methods using metaprogramming
Utilize the upcoming PageObject sections feature to create different "panels" within each page and then include those Panels into the page.
The first solution has the problem that each module can be included in other classes if somebody doesn't pay attention. It's not restricted to the single class
The second solution seems slow and not very "rubular", along with being confusing to update elements for those new to the project
The third solution seems like the best, but like the first solution, you could potentially include Sections into a class that they don't belong in.
What other way can I move the definition of these elements out of the class so that our class is cleaner, shorter, easier to read, and defined to Ruby Specifications (i.e. the Ruby Style Guide). They really just seem like config data rather than ruby code, so I feel like they don't belong in the class. Especially when we have 80+ elements in each class.
I don't see why you wouldn't keep the elements in the page object class. That's kind of the point of the class, right? If they're shared across multiple pages, then I understand putting them in a module and mixing in. But why abstract the unique elements on that page away from the page class?
But if you're absolutely going to do this, I'd think this is the best option:
Move elements for each PageObject into a corresponding module and include that module into a single PageObject only
There are ways you could ensure these modules are included only in the classes you expect. I have Module#included in mind. Something like:
module MyPageElements
def self.included cls
raise "Expected to be included on MyPage, got: #{cls}" unless cls == MyPage
end
# ... elements ...
end
create a YAML config file, with the mapping of element_type => element_name => element_id and then call the corresponding element methods using metaprogramming
Seems like this would be a headache to bring new, unfamiliar people up to speed on the code. Ultimately, I agree that it's just too un-Ruby like.
Utilize the upcoming PageObject sections feature to create different "panels" within each page and then include those Panels into the page.
Since I've just barely looked at this (thanks for linking me to the PR), I don't feel like I can speak to its efficacy.
I want to write some documentation in the module which should be at one point of my documentation. At this point I don't want to document all the classes/members of the module. This can be easily done with
..automodule:: myModule
:no-members:
However, at another point of my documentation I want to document all the classes of myModule. I could do this with
..automodule:: myModle
:members:
:noindex:
Unfortunately, this also includes the documentation of the module itself which I already have in my documentation and which I don't want to have here, again.
Is there a way to show only the documentation of all the members of myModule but not the documentation of myModule itself without having to list all the members manually?
Thanks to the comments I was able to solve the problem. Adding the following lines to conf.py does the trick:
def remove_module_docstring(app, what, name, obj, options, lines):
if what == "module" and name == "hpclogging.logger" and 'members' in options:
del lines[:]
def setup(app):
app.connect("autodoc-process-docstring", remove_module_docstring)
I am using Sphinx to document a python project. The documentation includes both an API reference and a user guide. I would like to include links from the user guide to the relevant section of the API reference, but can't seem to figure it out.
My API refrence uses the autodoc extension; however, I list my methods out individually, e.g.:
.. automodule:: module_name
.. autoclass:: class_name
.. automethod:: method_a
.. automethod:: method_b
In another rst file I have my user guide. I can link to an arbitrary place in another rst file using ref; however, it seems that the lable must come before a section title. So for instance the below doesn't work.
userguide.rst
see :ref:`my-reference-label` for more details on method_b
api.rst
.. automodule:: module_name
.. autoclass:: class_name
.. automethod:: method_a
.. _my-reference-label:
.. automethod:: method_b
How can a link to a specific place in my API documentation?
You don't need to define a label. A hyperlink to method_b can be created using the :py:meth: role:
:py:meth:`module_name.class_name.method_b`
This markup can be customized and simplified in various ways (for example, the :py prefix is not necessary when the domain is Python).
More details here:
http://sphinx-doc.org/markup/inline.html#cross-referencing-syntax
http://sphinx-doc.org/domains.html#cross-referencing-python-objects