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?
Related
I think both are used for namespace.
Modules are generally mixed into classes, right? So, what would be the purpose of defining a module inside a class?
Generally speaking modules have two uses:
Namespacing modules. When you nest stuff here and the module is intended only for specifying paths.
Functional modules. When the module has actual functionality that is intended to be called directly on the module or the module is intended to be included/extended.
Classes should be used for functionality only, even though Ruby doesn't enforce it.
Trying to do something but the above (like use module for both namespacing and functionality (1) or use a class for namespacing (2)) will generally confuse you.
(1) Some will disagree pointing to the rails' module with instance methods that also holds another module, called ClassMethods. I think it would have been cleaner if there was a module with two modules - ClassMethods and InstanceMethods instead.
(2) Some will disagree. A probably valid case is if you try to emulate private classes from other languages (where the private class will be nested inside your public class).
I would like to namespace my Ruby classes by putting them in a module. Indeed, this is a good idea if I decide to publish my Ruby gem so that the class names do not clash with existing classes in another gem. I know I can do the following for a class A::B:
module A
class B
end
end
However, the above is quite cumbersome in that I need to put all my class definitions into a single Ruby source file in order to scope them under the module. I would rather keep my class definitions in separate source files, much like a Java project, so how can I add classes to a module when they are all defined in separate files?
The accepted practice in this case is to wrap every file in module block
# a/b.rb
module A
class B
end
end
# a/c.rb
module A
class C
end
end
Btw. because of the way constant are resolved, it is advisable to use the long form I quoted above instead class A::B
(http://blog.honeybadger.io/avoid-these-traps-when-nesting-ruby-modules/).
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 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)