generator¶
This provides all of the functionality behind gendocs
and contains the Generator
class which is what you will need to use if you would like to start automatically documenting your packages.
Conventions¶
For gendocs
to work properly, we have re-defined the idea of packages and modules for the sake of gendocs
. A package can contain just about anything: classes, functions, modules, sub-module, etc.; while a module in the traditional sense can do the same, we re-define modules not to contain any further sub-modules. This re-definition allows gendocs
to mimic the structure of a Python package and automatically generate documentation pages containing the docstrings for the package!
What to Include¶
For gendocs
to work, every module being documented MUST contain an __all__
variable defining what is available to be documented. This variable ensures gendocs
does not recurse through external packages you might use internally.
Make sure to include an __all__
Note that only what is defined in this module’s__all__
list is what is accessible and what gets documented. Without an__all__
the documentation build will fail.
Some optional variables:
__displayname__
(str
): include this attribute to change how the heading for any documented element is displayed__category__
(str
): if any documented element contains this attribute, a statistics table is generated on the home page to count occurrences of various categories.
A Simple Use Case¶
If you only want to put up the documentation for your package, then set up sphinx documentation using sphinx-quickstart
(details) and stop after you’ve generated a new conf.py
. Edit the parameters of your configuration file appropriately and then add the following somewhere near the top:
# Import the package to document:
import wonderfulpackage
# Automatically generate documentation pages
from gendocs import Generator
Generator().DocumentPackages(wonderfulpackage)
That’s all you have to do! Now you can push your changes to a continuous integration like Read the Docs and have your entire package automatically documented.
Remove the Edit on GitHub
Be sure to remove the Edit on GitHub link from your project by following these steps.
Sophisticated Use Case¶
Private Members¶
It’s worth noting that you can control how private features are documented by passing an argument to the DocumentPackages
method:
# Import the package to document:
import wonderfulpackage
# Automatically generate documentation pages and show private members
from gendocs import Generator
Generator().DocumentPackages(wonderfulpackage, showprivate=True)
Custom Homepage¶
To use your own homepage to provide a project overview then create a .rst
file containing the content for your homepage and paste the relative file name to the DocumentPackages
method (we use our README for convenience):
# Import the package to document:
import wonderfulpackage
# Automatically generate documentation pages and show private members
from gendocs import Generator
gen = Generator()
gen.DocumentPackages(wonderfulpackage,
index_base='../../README.rst',
showprivate=True
)
Classifier¶
-
class
gendocs.generator.
Classifier
[source]¶ Bases:
object
-
static
GetClassText
(heading, name, showprivate=False, showinh=False)[source]¶ Returns the needed text to automatically document a class in RSF/sphinx
-
static
Generator¶
-
class
gendocs.generator.
Generator
(**kwargs)[source]¶ Bases:
properties.base.base.HasProperties
- An object to assist in the automatic generation of documentation pages
- for a given package. These methods iterate over a package and document each submodule as their own page. This class handles packages and modules in a very specific manner: - packages contain modules, classes, and functions - modules cannot contain sub-modules but only classes and functions
Required Properties:
- path (
String
): The top level directory to store all documentation content., a unicode string, Default: content
-
DocumentPackages
(packages, index_base=None, showprivate=False, notify=True, showinh=False, intro_pages=None, append_material=None, extra=None)[source]¶ This is the high level API to use to generate documentation pages for any given package(s).
Parameters:
-
_DocPackageFromTop
(packages, showprivate=False, showinh=False)[source]¶ Generates all of the documentation for given packages and appends new tocrees to the index. All documentation pages will be under the set relative path.
Parameters: Returns: The new content to append to the index
Return type:
-
_GenerateStaticsTable
(title='Current Statistics')[source]¶ Generates a statics table based on set categories
-
_MakePackagePages
(package, showprivate=False, nested=False, showinh=False)[source]¶ An internal helper to generate all of the pages for a given package
Parameters: Returns: The file names ready to be appended to a top-level toctree
Return type:
-
_ProduceContent
(mods, showprivate=False, showinh=False)[source]¶ An internal helper to create pages for several modules that do not have nested modules. This will automatically generate the needed RSF to document each module module and save the module to its own page appropriately.
Parameters: - mods (module) – The modules to document that do not contain nested modules
- showprivate (bool) – A flag for whether or not to display private members
Returns: The file names ready to be appended to a toctree
Return type:
-
_ProduceSingleContent
(mod, showprivate=False, showinh=False)[source]¶ An internal helper to create a page for a single module. This will automatically generate the needed RSF to document the module and save the module to its own page in its appropriate location.
Parameters: - mod (module) – The single module to document as its own page
- showprivate (bool) – A flag for whether or not to display private members
Returns: The file name ready to be appended to a toctree
Return type:
-
_class_validators
= {'_validate_props': <properties.handlers.ClassValidator object at 0x7f3d014297d0>}¶
-
_defaults
= {}¶
-
_prop_observers
= {}¶
-
_props
= {'path': <properties.basic.String object at 0x7f3d0139d150>}¶
-
path
¶ path (
String
) – The top level directory to store all documentation content., a unicode string, Default – content