From 9ca690489d8d862fda55eadfe7d70ad0cc41ed61 Mon Sep 17 00:00:00 2001 From: Lassi Tuura Date: Wed, 11 Jan 2012 15:13:47 +0100 Subject: [PATCH] Split module documentation into individual files. Default generate_modules.py produces documentation for all modules of a package into a single file. That is overwhelming amount in a single HTML page, split the documentation for each module into a separate file. This effectively imports the corresponding change from SiteDB, but with tweaks to make it work with WMCore's more nested structure. --- doc/Makefile | 2 +- doc/generate_modules.py | 57 ++++++++++++++++++++++++----------------- doc/wmcore/conf.py | 7 +++-- doc/wmcore/index.rst | 7 +---- 4 files changed, 40 insertions(+), 33 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 6f5a217ab0..96209fed6a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -34,7 +34,7 @@ $(PROJECT): [ -d $(PROJECT) ] || cp -rp wmcore $(PROJECT) apidoc: $(PROJECT) - python generate_modules.py -f -d $(PROJECT) -s rst $${PYTHONPATH%%:*}/WMCore + python generate_modules.py -f -d $(PROJECT) -s rst $${PYTHONPATH%%:*} cp references.rst $(PROJECT) html: apidoc diff --git a/doc/generate_modules.py b/doc/generate_modules.py index e38c943e9a..2a8654edc7 100644 --- a/doc/generate_modules.py +++ b/doc/generate_modules.py @@ -31,12 +31,7 @@ # automodule options -OPTIONS = ['members', - 'undoc-members', - # 'inherited-members', # disabled because there's a bug in sphinx - 'show-inheritance', - ] - +OPTIONS = ['members'] INIT = '__init__.py' def makename(package, module): @@ -77,41 +72,55 @@ def format_directive(module, package=None): def create_module_file(package, module, opts): """Build the text of the file and write the file.""" - text = format_heading(1, '%s Module' % module) - text += format_heading(2, ':mod:`%s` Module' % module) + text = format_heading(1, ':mod:`%s` Module' % module) text += format_directive(module, package) - write_file(makename(package, module), text, opts) + filename = makename(package, module) + write_file(filename, text, opts) + return filename + +def create_submodule_file(master_package, subroot, package, py_file, opts): + is_package = py_file == INIT + py_file = os.path.splitext(py_file)[0] + py_path = makename(subroot, py_file) + if is_package: + text = format_heading(2, ':mod:`%s` Package' % package) + text += format_directive(is_package and subroot or py_path, master_package) + text += '\n' + return (text, '') + else: + return ('', create_module_file(subroot, py_file, opts)) def create_package_file(root, master_package, subroot, py_files, opts, subs): """Build the text of the file and write the file.""" package = os.path.split(root)[-1] text = format_heading(1, '%s Package' % package) + toc = '' + # add each package's module for py_file in py_files: if shall_skip(os.path.join(root, py_file)): continue - is_package = py_file == INIT - py_file = os.path.splitext(py_file)[0] - py_path = makename(subroot, py_file) - if is_package: - heading = ':mod:`%s` Package' % package - else: - heading = ':mod:`%s` Module' % py_file - text += format_heading(2, heading) - text += format_directive(is_package and subroot or py_path, master_package) - text += '\n' + headpart, tocpart = create_submodule_file(master_package, subroot, package, py_file, opts) + if headpart: + text += headpart + if tocpart: + if not toc: + toc = format_heading(2, ':mod:`%s` Modules' % package) + toc += '.. toctree::\n\n' + toc += ' %s\n' % tocpart # build a list of directories that are packages (they contain an INIT file) subs = [sub for sub in subs if os.path.isfile(os.path.join(root, sub, INIT))] # if there are some package directories, add a TOC for theses subpackages if subs: - text += format_heading(2, 'Subpackages') - text += '.. toctree::\n\n' + toc += '\n' + toc += format_heading(2, 'Subpackages') + toc += '.. toctree::\n\n' for sub in subs: - text += ' %s.%s\n' % (makename(master_package, subroot), sub) - text += '\n' + toc += ' %s.%s\n' % (makename(master_package, subroot), sub) + toc += '\n' - write_file(makename(master_package, subroot), text, opts) + write_file(makename(master_package, subroot), text + toc, opts) def create_modules_toc_file(master_package, modules, opts, name='modules'): """ diff --git a/doc/wmcore/conf.py b/doc/wmcore/conf.py index 1c320758c6..598e9a4712 100644 --- a/doc/wmcore/conf.py +++ b/doc/wmcore/conf.py @@ -17,12 +17,15 @@ #exclude_trees = [] #default_role = None add_function_parentheses = True -add_module_names = True +add_module_names = False show_authors = True pygments_style = 'sphinx' #modindex_common_prefix = [] autoclass_content = 'both' +autodoc_member_order = 'bysource' +autodoc_default_flags = ['members', 'undoc-members', 'private-members', + 'special-members', 'show-inheritance'] html_theme = 'nature' #html_theme_options = {} @@ -42,7 +45,7 @@ html_show_sourcelink = False #html_use_opensearch = '' #html_file_suffix = '' -htmlhelp_basename = 'mondoc' +htmlhelp_basename = 'wmcdoc' latex_paper_size = 'a4' #latex_font_size = '10pt' diff --git a/doc/wmcore/index.rst b/doc/wmcore/index.rst index 0294b4c12c..725921990b 100644 --- a/doc/wmcore/index.rst +++ b/doc/wmcore/index.rst @@ -6,19 +6,14 @@ WMCore * **Version**: |version| * **Last modified**: |today| -Contents: ---------- - .. toctree:: :maxdepth: 2 introduction.rst changelog.rst + modules.rst references.rst -Indices and tables ------------------- - * :ref:`genindex` * :ref:`modindex` * :ref:`search`