PyDoc: resolve duplicate module warnings
Remove submodule listings from the module docstring, as this information already exists in the generator.
This commit is contained in:
parent
c69df6728a
commit
05710171cb
|
@ -5,17 +5,6 @@
|
||||||
--partial bmesh* ; cd doc/python_api ; sphinx-build sphinx-in sphinx-out ; cd ../../
|
--partial bmesh* ; cd doc/python_api ; sphinx-build sphinx-in sphinx-out ; cd ../../
|
||||||
|
|
||||||
|
|
||||||
Submodules:
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
bmesh.ops.rst
|
|
||||||
bmesh.types.rst
|
|
||||||
bmesh.utils.rst
|
|
||||||
bmesh.geometry.rst
|
|
||||||
|
|
||||||
|
|
||||||
Introduction
|
Introduction
|
||||||
------------
|
------------
|
||||||
|
|
||||||
|
|
|
@ -495,6 +495,13 @@ else:
|
||||||
bpy_struct = None
|
bpy_struct = None
|
||||||
|
|
||||||
|
|
||||||
|
def import_value_from_module(module_name, import_name):
|
||||||
|
ns = {}
|
||||||
|
exec_str = "from %s import %s as value" % (module_name, import_name)
|
||||||
|
exec(exec_str, ns, ns)
|
||||||
|
return ns["value"]
|
||||||
|
|
||||||
|
|
||||||
def escape_rst(text):
|
def escape_rst(text):
|
||||||
""" Escape plain text which may contain characters used by RST.
|
""" Escape plain text which may contain characters used by RST.
|
||||||
"""
|
"""
|
||||||
|
@ -749,7 +756,7 @@ def pyprop2sphinx(ident, fw, identifier, py_prop):
|
||||||
fw(ident + " (readonly)\n\n")
|
fw(ident + " (readonly)\n\n")
|
||||||
|
|
||||||
|
|
||||||
def pymodule2sphinx(basepath, module_name, module, title):
|
def pymodule2sphinx(basepath, module_name, module, title, module_all_extra):
|
||||||
import types
|
import types
|
||||||
attribute_set = set()
|
attribute_set = set()
|
||||||
filepath = os.path.join(basepath, module_name + ".rst")
|
filepath = os.path.join(basepath, module_name + ".rst")
|
||||||
|
@ -796,22 +803,25 @@ def pymodule2sphinx(basepath, module_name, module, title):
|
||||||
fw(module.__doc__.strip())
|
fw(module.__doc__.strip())
|
||||||
fw("\n\n")
|
fw("\n\n")
|
||||||
|
|
||||||
write_example_ref("", fw, module_name)
|
|
||||||
|
|
||||||
# write submodules
|
# write submodules
|
||||||
# we could also scan files but this ensures __all__ is used correctly
|
# we could also scan files but this ensures __all__ is used correctly
|
||||||
if module_all is not None:
|
if module_all or module_all_extra:
|
||||||
submod_name = None
|
submod_name = None
|
||||||
submod = None
|
submod = None
|
||||||
submod_ls = []
|
submod_ls = []
|
||||||
for submod_name in module_all:
|
for submod_name in (module_all or ()):
|
||||||
ns = {}
|
submod = import_value_from_module(module_name, submod_name)
|
||||||
exec_str = "from %s import %s as submod" % (module.__name__, submod_name)
|
|
||||||
exec(exec_str, ns, ns)
|
|
||||||
submod = ns["submod"]
|
|
||||||
if type(submod) == types.ModuleType:
|
if type(submod) == types.ModuleType:
|
||||||
submod_ls.append((submod_name, submod))
|
submod_ls.append((submod_name, submod))
|
||||||
|
|
||||||
|
for submod_name in module_all_extra:
|
||||||
|
if submod_name in attribute_set:
|
||||||
|
continue
|
||||||
|
submod = import_value_from_module(module_name, submod_name)
|
||||||
|
# No type checks, since there are non-module types we treat as modules
|
||||||
|
# such as `bpy.app.translations` & `bpy.app.handlers`.
|
||||||
|
submod_ls.append((submod_name, submod))
|
||||||
|
|
||||||
del submod_name
|
del submod_name
|
||||||
del submod
|
del submod
|
||||||
|
|
||||||
|
@ -821,17 +831,22 @@ def pymodule2sphinx(basepath, module_name, module, title):
|
||||||
|
|
||||||
for submod_name, submod in submod_ls:
|
for submod_name, submod in submod_ls:
|
||||||
submod_name_full = "%s.%s" % (module_name, submod_name)
|
submod_name_full = "%s.%s" % (module_name, submod_name)
|
||||||
fw(" %s.rst\n\n" % submod_name_full)
|
fw(" %s.rst\n" % submod_name_full)
|
||||||
|
|
||||||
pymodule2sphinx(basepath, submod_name_full, submod, "%s submodule" % module_name)
|
pymodule2sphinx(basepath, submod_name_full, submod, "%s submodule" % module_name, ())
|
||||||
|
fw("\n")
|
||||||
del submod_ls
|
del submod_ls
|
||||||
# done writing submodules!
|
# done writing submodules!
|
||||||
|
|
||||||
|
write_example_ref("", fw, module_name)
|
||||||
|
|
||||||
# write members of the module
|
# write members of the module
|
||||||
# only tested with PyStructs which are not exactly modules
|
# only tested with PyStructs which are not exactly modules
|
||||||
for key, descr in sorted(type(module).__dict__.items()):
|
for key, descr in sorted(type(module).__dict__.items()):
|
||||||
if key.startswith("__"):
|
if key.startswith("__"):
|
||||||
continue
|
continue
|
||||||
|
if key in module_all_extra:
|
||||||
|
continue
|
||||||
# naughty, we also add getset's into PyStructs, this is not typical py but also not incorrect.
|
# naughty, we also add getset's into PyStructs, this is not typical py but also not incorrect.
|
||||||
|
|
||||||
# type_name is only used for examples and messages
|
# type_name is only used for examples and messages
|
||||||
|
@ -854,6 +869,8 @@ def pymodule2sphinx(basepath, module_name, module, title):
|
||||||
# sort by the valye type
|
# sort by the valye type
|
||||||
descr_sorted.sort(key=lambda descr_data: str(descr_data[3]))
|
descr_sorted.sort(key=lambda descr_data: str(descr_data[3]))
|
||||||
for key, descr, value, value_type in descr_sorted:
|
for key, descr, value, value_type in descr_sorted:
|
||||||
|
if key in module_all_extra:
|
||||||
|
continue
|
||||||
|
|
||||||
# must be documented as a submodule
|
# must be documented as a submodule
|
||||||
if is_struct_seq(value):
|
if is_struct_seq(value):
|
||||||
|
@ -895,6 +912,9 @@ def pymodule2sphinx(basepath, module_name, module, title):
|
||||||
module_dir_value_type.sort(key=lambda triple: str(triple[2]))
|
module_dir_value_type.sort(key=lambda triple: str(triple[2]))
|
||||||
|
|
||||||
for attribute, value, value_type in module_dir_value_type:
|
for attribute, value, value_type in module_dir_value_type:
|
||||||
|
if attribute in module_all_extra:
|
||||||
|
continue
|
||||||
|
|
||||||
if value_type == FunctionType:
|
if value_type == FunctionType:
|
||||||
pyfunc2sphinx("", fw, module_name, None, attribute, value, is_class=False)
|
pyfunc2sphinx("", fw, module_name, None, attribute, value, is_class=False)
|
||||||
# both the same at the moment but to be future proof
|
# both the same at the moment but to be future proof
|
||||||
|
@ -1895,7 +1915,7 @@ def write_rst_msgbus(basepath):
|
||||||
file.close()
|
file.close()
|
||||||
|
|
||||||
# Write the contents.
|
# Write the contents.
|
||||||
pymodule2sphinx(basepath, 'bpy.msgbus', bpy.msgbus, 'Message Bus')
|
pymodule2sphinx(basepath, 'bpy.msgbus', bpy.msgbus, 'Message Bus', ())
|
||||||
EXAMPLE_SET_USED.add("bpy.msgbus")
|
EXAMPLE_SET_USED.add("bpy.msgbus")
|
||||||
|
|
||||||
|
|
||||||
|
@ -1947,6 +1967,7 @@ def write_rst_importable_modules(basepath):
|
||||||
"gpu.select": "GPU Select",
|
"gpu.select": "GPU Select",
|
||||||
"gpu.shader": "GPU Shader",
|
"gpu.shader": "GPU Shader",
|
||||||
"bmesh": "BMesh Module",
|
"bmesh": "BMesh Module",
|
||||||
|
"bmesh.ops": "BMesh Operators",
|
||||||
"bmesh.types": "BMesh Types",
|
"bmesh.types": "BMesh Types",
|
||||||
"bmesh.utils": "BMesh Utilities",
|
"bmesh.utils": "BMesh Utilities",
|
||||||
"bmesh.geometry": "BMesh Geometry Utilities",
|
"bmesh.geometry": "BMesh Geometry Utilities",
|
||||||
|
@ -1972,11 +1993,32 @@ def write_rst_importable_modules(basepath):
|
||||||
"freestyle.shaders": "Freestyle Shaders",
|
"freestyle.shaders": "Freestyle Shaders",
|
||||||
"freestyle.utils": "Freestyle Utilities",
|
"freestyle.utils": "Freestyle Utilities",
|
||||||
}
|
}
|
||||||
|
|
||||||
|
# This is needed since some of the sub-modules listed above are not actual modules.
|
||||||
|
# Examples include `bpy.app.translations` & `bpy.app.handlers`.
|
||||||
|
#
|
||||||
|
# Most of these are `PyStructSequence` internally,
|
||||||
|
# however we don't want to document all of these as modules since some only contain
|
||||||
|
# a few values (version number for e.g).
|
||||||
|
#
|
||||||
|
# If we remove this logic and document all `PyStructSequence` as sub-modules it means
|
||||||
|
# `bpy.app.timers` for example would be presented on the same level as library information
|
||||||
|
# access such as `bpy.app.sdl` which doesn't seem useful since it hides more useful
|
||||||
|
# module-like objects among library data access.
|
||||||
|
importable_modules_parent_map = {}
|
||||||
|
for mod_name in importable_modules.keys():
|
||||||
|
if mod_name in EXCLUDE_MODULES:
|
||||||
|
continue
|
||||||
|
if "." in mod_name:
|
||||||
|
mod_name, submod_name = mod_name.rsplit(".", 1)
|
||||||
|
importable_modules_parent_map.setdefault(mod_name, []).append(submod_name)
|
||||||
|
|
||||||
for mod_name, mod_descr in importable_modules.items():
|
for mod_name, mod_descr in importable_modules.items():
|
||||||
if mod_name not in EXCLUDE_MODULES:
|
if mod_name in EXCLUDE_MODULES:
|
||||||
module = __import__(mod_name,
|
continue
|
||||||
fromlist=[mod_name.rsplit(".", 1)[-1]])
|
module_all_extra = importable_modules_parent_map.get(mod_name, ())
|
||||||
pymodule2sphinx(basepath, mod_name, module, mod_descr)
|
module = __import__(mod_name, fromlist=[mod_name.rsplit(".", 1)[-1]])
|
||||||
|
pymodule2sphinx(basepath, mod_name, module, mod_descr, module_all_extra)
|
||||||
|
|
||||||
|
|
||||||
def copy_handwritten_rsts(basepath):
|
def copy_handwritten_rsts(basepath):
|
||||||
|
|
|
@ -106,19 +106,8 @@ success:
|
||||||
* \{ */
|
* \{ */
|
||||||
|
|
||||||
PyDoc_STRVAR(GPU_doc,
|
PyDoc_STRVAR(GPU_doc,
|
||||||
"This module provides Python wrappers for the GPU implementation in Blender. "
|
"This module provides Python wrappers for the GPU implementation in Blender.\n"
|
||||||
"Some higher level functions can be found in the `gpu_extras` module. "
|
"Some higher level functions can be found in the `gpu_extras` module.");
|
||||||
"\n\n"
|
|
||||||
"Submodules:\n"
|
|
||||||
"\n"
|
|
||||||
".. toctree::\n"
|
|
||||||
" :maxdepth: 1\n"
|
|
||||||
"\n"
|
|
||||||
" gpu.types.rst\n"
|
|
||||||
" gpu.shader.rst\n"
|
|
||||||
" gpu.matrix.rst\n"
|
|
||||||
" gpu.select.rst\n"
|
|
||||||
"\n");
|
|
||||||
static struct PyModuleDef GPU_module_def = {
|
static struct PyModuleDef GPU_module_def = {
|
||||||
PyModuleDef_HEAD_INIT,
|
PyModuleDef_HEAD_INIT,
|
||||||
.m_name = "gpu",
|
.m_name = "gpu",
|
||||||
|
|
|
@ -126,17 +126,7 @@ static PyStructSequence_Field app_info_fields[] = {
|
||||||
};
|
};
|
||||||
|
|
||||||
PyDoc_STRVAR(bpy_app_doc,
|
PyDoc_STRVAR(bpy_app_doc,
|
||||||
"This module contains application values that remain unchanged during runtime.\n"
|
"This module contains application values that remain unchanged during runtime.");
|
||||||
"\n"
|
|
||||||
"Submodules:\n"
|
|
||||||
"\n"
|
|
||||||
".. toctree::\n"
|
|
||||||
" :maxdepth: 1\n"
|
|
||||||
"\n"
|
|
||||||
" bpy.app.handlers.rst\n"
|
|
||||||
" bpy.app.icons.rst\n"
|
|
||||||
" bpy.app.timers.rst\n"
|
|
||||||
" bpy.app.translations.rst\n");
|
|
||||||
|
|
||||||
static PyStructSequence_Desc app_info_desc = {
|
static PyStructSequence_Desc app_info_desc = {
|
||||||
"bpy.app", /* name */
|
"bpy.app", /* name */
|
||||||
|
|
|
@ -39,18 +39,7 @@ PyDoc_STRVAR(
|
||||||
".. note::\n"
|
".. note::\n"
|
||||||
"\n"
|
"\n"
|
||||||
" Classes, methods and attributes that accept vectors also accept other numeric sequences,\n"
|
" Classes, methods and attributes that accept vectors also accept other numeric sequences,\n"
|
||||||
" such as tuples, lists."
|
" such as tuples, lists.\n"
|
||||||
"\n\n"
|
|
||||||
"Submodules:\n"
|
|
||||||
"\n"
|
|
||||||
".. toctree::\n"
|
|
||||||
" :maxdepth: 1\n"
|
|
||||||
"\n"
|
|
||||||
" mathutils.geometry.rst\n"
|
|
||||||
" mathutils.bvhtree.rst\n"
|
|
||||||
" mathutils.kdtree.rst\n"
|
|
||||||
" mathutils.interpolate.rst\n"
|
|
||||||
" mathutils.noise.rst\n"
|
|
||||||
"\n"
|
"\n"
|
||||||
"The :mod:`mathutils` module provides the following classes:\n"
|
"The :mod:`mathutils` module provides the following classes:\n"
|
||||||
"\n"
|
"\n"
|
||||||
|
|
Loading…
Reference in New Issue