From 7561797c5d68f2e083b5b93c1ad0a829b235424f Mon Sep 17 00:00:00 2001 From: Branko Majic Date: Sat, 13 May 2017 13:37:43 +0200 Subject: [PATCH] Implement ability to limit module documentation building: - Added new option to plugin_formatter.py to support passing-in a list of modules for which the documentation should be built. - Updated docuemtnation Makefile to allow specifying list of modules via environment variables (defaulting to all modules). - Update instructions for building documentation and module development to include commands and description of limiting module documentation builds. --- docs/bin/plugin_formatter.py | 15 +++++++++++---- docs/docsite/Makefile | 6 +++++- docs/docsite/README.md | 5 +++++ .../dev_guide/developing_modules_documenting.rst | 7 +++++++ 4 files changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index 319b38d1c059b6..206aa03b21daec 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -125,12 +125,13 @@ def write_data(text, options, outputname, module): ##################################################################################### -def list_modules(module_dir, depth=0): +def list_modules(module_dir, depth=0, limit_to_modules="all"): ''' returns a hash of categories, each category being a hash of module names to file paths ''' categories = dict() module_info = dict() aliases = defaultdict(set) + module_limit = limit_to_modules.split(",") # * windows powershell modules have documentation stubs in python docstring # format (they are not executed) so skip the ps1 format files @@ -167,8 +168,12 @@ def list_modules(module_dir, depth=0): aliases[source].add(module) continue - category[module] = module_path - module_info[module] = module_path + # Limit documentation building only to passed-in modules. The "none" + # below is not a typo (it should not be None). String "none" denotes + # don't build any module documentation. + if "none" not in module_limit and ("all" in module_limit or module in module_limit): + category[module] = module_path + module_info[module] = module_path # keep module tests out of becoming module docs if 'test' in categories: @@ -194,6 +199,8 @@ def generate_parser(): p.add_option("-v", "--verbose", action='store_true', default=False, help="Verbose") p.add_option("-o", "--output-dir", action="store", dest="output_dir", default=None, help="Output directory for module files") p.add_option("-I", "--includes-file", action="store", dest="includes_file", default=None, help="Create a file containing list of processed modules") + p.add_option("-l", "--limit-to-modules", action="store", dest="limit_to_modules", default="all", + help="Limit building module documentation to comma-separated list of modules. Specify 'all' or 'none' for all/no modules.") p.add_option('-V', action='version', help='Show version number and exit') return p @@ -447,7 +454,7 @@ def main(): env, template, outputname = jinja2_environment(options.template_dir, options.type) - mod_info, categories, aliases = list_modules(options.module_dir) + mod_info, categories, aliases = list_modules(options.module_dir, limit_to_modules=options.limit_to_modules) categories['all'] = mod_info categories['_aliases'] = aliases category_names = [c for c in categories.keys() if not c.startswith('_')] diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index 31e5895b10dfae..eb9f01b154fbbf 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -8,6 +8,10 @@ else CPUS ?= $(shell nproc) endif +# Assume we are building documentation for all modules unless specified +# otherwise via environment variable. +MODULES ?= all + all: docs docs: clean htmldocs @@ -44,7 +48,7 @@ keywords: $(FORMATTER) ../templates/playbooks_keywords.rst.j2 PYTHONPATH=../../lib $(DUMPER) --template-dir=../templates --output-dir=rst/ -d ./keyword_desc.yml modules: $(FORMATTER) ../templates/plugin.rst.j2 - PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ + PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ -l $(MODULES) staticmin: cat _themes/srtd/static/css/theme.css | sed -e 's/^[ ]*//g; s/[ ]*$$//g; s/\([:{;,]\) /\1/g; s/ {/{/g; s/\/\*.*\*\///g; /^$$/d' | sed -e :a -e '$$!N; s/\n\(.\)/\1/; ta' > _themes/srtd/static/css/theme.min.css diff --git a/docs/docsite/README.md b/docs/docsite/README.md index 21985a8f6aa0c5..f68349c1d1f072 100644 --- a/docs/docsite/README.md +++ b/docs/docsite/README.md @@ -14,6 +14,11 @@ such as link references, you may install sphinx and build the documentation by r To include module documentation you'll need to run `make webdocs` at the top level of the repository. The generated html files are in docsite/htmlout/. +To limit module documentation building to a specific module, run `MODULES=NAME +make webdocs` instead. This should make testing module documentation syntax much +faster. Instead of a single module, you can also specify a comma-separated list +of modules, or keywords `all` and `none`. + If you do not want to learn the reStructuredText format, you can also [file issues] about documentation problems on the Ansible GitHub project. diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 3ecb4132ba9765..83b2b35c591d22 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -338,6 +338,13 @@ Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` direc run the command: ``make webdocs``. The new 'modules.html' file will be built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory. +In order to limit module documentation building to the module you are working on +(and therefore speeding the build process by quite a bit), run the command: +``MODULES=$MODULENAME make webdocs``. The ``MODULES`` environment variable +accepts a comma-separated list of module names, or special keywords ``all`` (for +building documentation for all modules) and ``none`` (for skipping the module +documentation building process entirely). + To test your documentation against your ``argument_spec`` you can use ``validate-modules``. Note that this option isn't currently enabled in Shippable due to the time it takes to run. .. code-block:: bash