Merge pull request #467 from marcbonnici/documentation

Documentation Update

doc/Makefile

@@ -7,18 +7,11 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
 
-SPHINXAPI     = sphinx-apidoc
-SPHINXAPIOPTS =
-
-WAEXT         = ./build_extension_docs.py
-WAEXTOPTS     = source/extensions ../wlauto  ../wlauto/external ../wlauto/tests
-
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-ALLSPHINXAPIOPTS = -f $(SPHINXAPIOPTS) -o source/api ../wlauto
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
@@ -58,52 +51,38 @@ coverage:
 	@echo
 	@echo "Build finished. The coverage reports are in $(BUILDDIR)/coverage."
 
-api: ../wlauto
-	rm -rf source/api/*
-	$(SPHINXAPI) $(ALLSPHINXAPIOPTS)
-
-waext: ../wlauto
-	rm -rf source/extensions
-	mkdir -p source/extensions
-	$(WAEXT) $(WAEXTOPTS) 
-
-
-sigtab: ../wlauto/core/instrumentation.py source/instrumentation_method_map.template
-	rm -rf source/instrumentation_method_map.rst
-	./build_instrumentation_method_map.py source/instrumentation_method_map.rst
-
-html: api waext sigtab
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: api waext sigtab
+dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml: api waext sigtab
+singlehtml:
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle: api waext sigtab
+pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json: api waext sigtab
+json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: api waext sigtab
+htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp: api waext sigtab
+qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -112,7 +91,7 @@ qthelp: api waext sigtab
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/WorkloadAutomation2.qhc"
 
-devhelp: api
+devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -121,64 +100,64 @@ devhelp: api
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/WorkloadAutomation2"
 	@echo "# devhelp"
 
-epub: api waext sigtab
+epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex: api waext sigtab
+latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf: api waext sigtab
+latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-text: api waext sigtab
+text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man: api waext sigtab
+man:
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo: api waext sigtab
+texinfo:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
-info: api waext sigtab
+info:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
-gettext: api waext sigtab
+gettext:
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes: api waext sigtab
+changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck: api waext sigtab
+linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-doctest: api waext sigtab
+doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."

doc/build_extension_docs.py

@@ -17,6 +17,7 @@
 
 import os
 import sys
+import shutil
 
 from wlauto import ExtensionLoader
 from wlauto.utils.doc import get_rst_from_extension, underline
@@ -30,6 +31,9 @@ def generate_extension_documentation(source_dir, outdir, ignore_paths):
     loader = ExtensionLoader(keep_going=True)
     loader.clear()
     loader.update(paths=[source_dir], ignore_paths=ignore_paths)
+    if os.path.exists(outdir):
+        shutil.rmtree(outdir)
+    os.makedirs(outdir)
     for ext_type in loader.extension_kinds:
         if not ext_type in GENERATE_FOR:
             continue

doc/build_instrumentation_method_map.py

@@ -16,7 +16,6 @@
 import os
 import sys
 import string
-from copy import copy
 
 from wlauto.core.instrumentation import SIGNAL_MAP, PRIORITY_MAP
 from wlauto.utils.doc import format_simple_table
@@ -25,7 +24,7 @@ from wlauto.utils.doc import format_simple_table
 CONVINIENCE_ALIASES = ['initialize', 'setup', 'start', 'stop', 'process_workload_result',
                        'update_result', 'teardown', 'finalize']
 
-OUTPUT_TEMPLATE_FILE =  os.path.join(os.path.dirname(__file__), 'source', 'instrumentation_method_map.template')
+OUTPUT_TEMPLATE_FILE = os.path.join(os.path.dirname(__file__), 'source', 'instrumentation_method_map.template')
 
 
 def escape_trailing_underscore(value):
@@ -37,7 +36,9 @@ def generate_instrumentation_method_map(outfile):
     signal_table = format_simple_table([(k, v) for k, v in SIGNAL_MAP.iteritems()],
                                        headers=['method name', 'signal'], align='<<')
     priority_table = format_simple_table([(escape_trailing_underscore(k), v)  for k, v in PRIORITY_MAP.iteritems()],
-                                         headers=['prefix', 'priority'],  align='<>')
+                                         headers=['prefix', 'priority'], align='<>')
+    if os.path.isfile(outfile):
+        os.unlink(outfile)
     with open(OUTPUT_TEMPLATE_FILE) as fh:
         template = string.Template(fh.read())
     with open(outfile, 'w') as wfh:

doc/requirements.txt

@@ -0,0 +1 @@
+nose

doc/source/agenda.rst

@@ -147,7 +147,7 @@ to 15 million. You can specify this using dhrystone's parameters:
 
                 wa show dhrystone
 
-          see the :ref:`Invocation` section for details.
+          see the :ref:`Invocation <invocation>` section for details.
 
 In addition to configuring the workload itself, we can also specify
 configuration for the underlying device. This can be done by setting runtime

doc/source/conf.py

@@ -28,12 +28,16 @@
 
 import sys, os
 import warnings
+from sphinx.apidoc import main
 
 warnings.filterwarnings('ignore', "Module louie was already imported")
 
 this_dir = os.path.dirname(__file__)
+sys.path.insert(0, os.path.join(this_dir, '..'))
 sys.path.insert(0, os.path.join(this_dir, '../..'))
 import wlauto
+from build_extension_docs import generate_extension_documentation
+from build_instrumentation_method_map import generate_instrumentation_method_map
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -264,7 +268,21 @@ texinfo_documents = [
 #texinfo_show_urls = 'footnote'
 
 
+def run_apidoc(_):
+    sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+    cur_dir = os.path.abspath(os.path.dirname(__file__))
+    api_output = os.path.join(cur_dir, 'api')
+    module = os.path.join(cur_dir, '..', '..', 'wlauto')
+    main(['-f', '-o', api_output, module, '--force'])
+
 def setup(app):
+    module_dir = os.path.join('..', '..', 'wlauto')
+    excluded_extensions = [os.path.join(module_dir, 'external'),
+                           os.path.join(module_dir, 'tests')]
+    os.chdir(os.path.dirname(__file__))
+    app.connect('builder-inited', run_apidoc)
+    generate_instrumentation_method_map('instrumentation_method_map.rst')
+    generate_extension_documentation(module_dir, 'extensions', excluded_extensions)
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')

doc/source/writing_extensions.rst

@@ -964,7 +964,7 @@ that accompanies them, in addition to what has been outlined here, should
 provide enough guidance.
 
 :commands: This allows extending WA with additional sub-commands (to supplement
-           exiting ones outlined in the :ref:`invocation` section).
+           exiting ones outlined in the :ref:`invocation <invocation>` section).
 :modules: Modules are "extensions for extensions". They can be loaded by other
           extensions to expand their functionality (for example, a flashing
           module maybe loaded by a device in order to support flashing).

wlauto/core/bootstrap.py

@@ -152,7 +152,8 @@ def init_environment(env_root, dep_dir, extension_paths, overwrite_existing=Fals
     os.makedirs(env_root)
     with open(os.path.join(_this_dir, '..', 'config_example.py')) as rf:
         text = re.sub(r'""".*?"""', '', rf.read(), 1, re.DOTALL)
-        with open(os.path.join(_env_root, 'config.py'), 'w') as wf:
+        config_path = os.path.join(env_root, 'config.py')
+        with open(config_path, 'w') as wf:
             wf.write(text)
 
     os.makedirs(dep_dir)
@@ -173,9 +174,11 @@ def init_environment(env_root, dep_dir, extension_paths, overwrite_existing=Fals
                     os.chown(os.path.join(root, d), uid, gid)
                 for f in files:  # pylint: disable=W0621
                     os.chown(os.path.join(root, f), uid, gid)
+    return config_path
 
 
 _env_root = os.getenv('WA_USER_DIRECTORY', os.path.join(_user_home, '.workload_automation'))
+_env_root = os.path.abspath(_env_root)
 _dep_dir = os.path.join(_env_root, 'dependencies')
 _extension_paths = [os.path.join(_env_root, ext.default_path) for ext in _extensions]
 _env_var_paths = os.getenv('WA_EXTENSION_PATHS', '')
@@ -189,7 +192,8 @@ for filename in ['config.py', 'config.yaml']:
         _env_configs.append(filepath)
 
 if not os.path.isdir(_env_root):
-    init_environment(_env_root, _dep_dir, _extension_paths)
+    cfg_path = init_environment(_env_root, _dep_dir, _extension_paths)
+    _env_configs.append(cfg_path)
 elif not _env_configs:
     filepath = os.path.join(_env_root, 'config.py')
     with open(os.path.join(_this_dir, '..', 'config_example.py')) as f: