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)
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
I currently creating a gem, so, I have a folder with different files, which contains different classes, this folder will be updated with more files and also current ones will be updated as well, in another file I have a module that should contain these classes.
Currently, I add manually to the module all the classes:
File1.rb:
module MyModule
class ClassA
# code here
end
end
File2.rb:
module MyModule
class ClassB
# code here
end
end
But, since I will add more classes and current classes will be updated this is not optimal and very dangerous to maintain clean, so is there any other way to add classes in different files in one module set in another file?
Thanks in advance
No there is no another way and I don't see any danger in doing it the way you did (correct way).
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.
I am a starter with ruby, I searched that if someone else has asked similar question but was not able to find any. so I am asking it here.
I am trying my hand at modules in ruby.
I created a folder Project
inside Project folder, created a class One
class Project::One
include Project::Rest
end
inside Project folder, created a module Rest
module Project::Rest
def display
puts "in display"
end
end
but when I try to run the program(ruby one.rb) I get the
uninitialized constant Project (NameError)
Please help me
The problem is that you never actually define the Project constant. You have to define it before you can use it. Example:
# root.rb
module Project
end
require "project/test"
# project/test.rb
class Project::Test
end
You should then be able to run ruby root.rb. Another approach is to state the module in the namespace.
# root.rb
require "project/test"
# project/test.rb
module Project
class Test
end
end
With this example, you are able to run ruby project/test.rb as well, since the Project module is defined in that file.
And if you have multiple files defining the Project module, that's not a problem either. It won't be re-defined, it will always be the same module.
Both of these methods will define the Project module. Simply going Project::Test will not, however, define the module.
As a sidenote, Rails has a auto loader. If you're in a rails app, and use a certain folder structure, these kind of intermediate modules will be defined for you. Without Rails, though, you have to define them yourself.
The issue is that you're not nesting your classes/modules correctly. You have to declare a module with the module keyword, not merely by writing class Project::Class. Assuming you have this structure:
Project/
one.rb
rest.rb
then your files should look something like this:
# one.rb
require 'rest'
module Project
class One
include Project::Rest
end
end
# rest.rb
module Project
module Rest
def display
puts 'in display'
end
end
end
Note how the modules are nested in these examples.
If you have code in multiple files, you have to load those files before you can access what's in them. This is usually done with a require statement. I think what you want to do should look like this:
# one.rb
require 'rest'
module Project
class One
include Rest
end
end
# rest.rb
module Project
module Rest
def display
puts "in display"
end
end
end