From 5f8de423f190bbb79a62f804151bc24824fa32d8 Mon Sep 17 00:00:00 2001 From: "Matt A. Tobin" Date: Fri, 2 Feb 2018 04:16:08 -0500 Subject: Add m-esr52 at 52.6.0 --- tools/docs/Vagrantfile | 13 ++++ tools/docs/conf.py | 83 ++++++++++++++++++++++++ tools/docs/index.rst | 58 +++++++++++++++++ tools/docs/mach_commands.py | 117 ++++++++++++++++++++++++++++++++++ tools/docs/moztreedocs/__init__.py | 126 +++++++++++++++++++++++++++++++++++++ 5 files changed, 397 insertions(+) create mode 100644 tools/docs/Vagrantfile create mode 100644 tools/docs/conf.py create mode 100644 tools/docs/index.rst create mode 100644 tools/docs/mach_commands.py create mode 100644 tools/docs/moztreedocs/__init__.py (limited to 'tools/docs') diff --git a/tools/docs/Vagrantfile b/tools/docs/Vagrantfile new file mode 100644 index 000000000..247afe1b3 --- /dev/null +++ b/tools/docs/Vagrantfile @@ -0,0 +1,13 @@ +# -*- mode: ruby -*- +# vi: set ft=ruby : + +# We intentionally use the old config format because Mozilla's Jenkins +# server doesn't run a modern Vagrant. +Vagrant::Config.run do |config| + config.vm.box = "precise64" + config.vm.box_url = "http://files.vagrantup.com/precise64.box" + config.vm.share_folder("gecko", "/gecko", "../..") + # Doxygen needs more than the default memory or it will swap and be + # extremely slow. + config.vm.customize ["modifyvm", :id, "--memory", 2048] +end diff --git a/tools/docs/conf.py b/tools/docs/conf.py new file mode 100644 index 000000000..38cea035a --- /dev/null +++ b/tools/docs/conf.py @@ -0,0 +1,83 @@ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, You can obtain one at http://mozilla.org/MPL/2.0/. + +from __future__ import unicode_literals + +import os +import re +import sys + +from datetime import datetime + +# Set up Python environment to load build system packages. +OUR_DIR = os.path.dirname(__file__) +topsrcdir = os.path.normpath(os.path.join(OUR_DIR, '..', '..')) + +EXTRA_PATHS = ( + 'layout/tools/reftest', + 'python/futures', + 'python/jsmin', + 'python/mach', + 'python/mozbuild', + 'python/mozversioncontrol', + 'python/which', + 'testing/mozbase/manifestparser', + 'testing/mozbase/mozfile', + 'testing/mozbase/mozprocess', +) + +sys.path[:0] = [os.path.join(topsrcdir, p) for p in EXTRA_PATHS] + +sys.path.insert(0, OUR_DIR) + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.graphviz', + 'sphinx.ext.todo', + 'mozbuild.sphinx', +] + +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +project = u'Mozilla Source Tree Docs' +year = datetime.now().year + +# Grab the version from the source tree's milestone. +# FUTURE Use Python API from bug 941299. +with open(os.path.join(topsrcdir, 'config', 'milestone.txt'), 'rt') as fh: + for line in fh: + line = line.strip() + + if not line or line.startswith('#'): + continue + + release = line + break + +version = re.sub(r'[ab]\d+$', '', release) + +exclude_patterns = ['_build', '_staging', '_venv'] +pygments_style = 'sphinx' + +# We need to perform some adjustment of the settings and environment +# when running on Read The Docs. +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if on_rtd: + # SHELL isn't set on RTD and mach.mixin.process's import raises if a + # shell-related environment variable can't be found. Set the variable here + # to hack us into working on RTD. + assert 'SHELL' not in os.environ + os.environ['SHELL'] = '/bin/bash' +else: + # We only need to set the RTD theme when not on RTD because the RTD + # environment handles this otherwise. + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + +html_static_path = ['_static'] +htmlhelp_basename = 'MozillaTreeDocs' diff --git a/tools/docs/index.rst b/tools/docs/index.rst new file mode 100644 index 000000000..ae2a9d593 --- /dev/null +++ b/tools/docs/index.rst @@ -0,0 +1,58 @@ +================================= +Mozilla Source Tree Documentation +================================= + +.. toctree:: + :maxdepth: 1 + + {indexes} + +Python Packages +=============== + +.. toctree:: + :maxdepth: 2 + + {python_packages} + +Managing Documentation +====================== + +This documentation is generated via the +`Sphinx `_ tool from sources in the tree. + +To build the documentation, run ``mach doc``. Run +``mach help doc`` to see configurable options. + +Adding Documentation +-------------------- + +To add new documentation, define the ``SPHINX_TREES`` and +``SPHINX_PYTHON_PACKAGE_DIRS`` variables in ``moz.build`` files in +the tree and documentation will automatically get picked up. + +Say you have a directory ``featureX`` you would like to write some +documentation for. Here are the steps to create Sphinx documentation +for it: + +1. Create a directory for the docs. This is typically ``docs``. e.g. + ``featureX/docs``. +2. Create an ``index.rst`` file in this directory. The ``index.rst`` file + is the root documentation for that section. See ``build/docs/index.rst`` + for an example file. +3. In a ``moz.build`` file (typically the one in the parent directory of + the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing. + e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs`` + directory under the current directory should be installed into the + Sphinx documentation tree under ``/featureX``*. +4. If you have Python packages you would like to generate Python API + documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to + declare directories containing Python packages. e.g. + ``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/tools/docs/mach_commands.py b/tools/docs/mach_commands.py new file mode 100644 index 000000000..825e5ec38 --- /dev/null +++ b/tools/docs/mach_commands.py @@ -0,0 +1,117 @@ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, # You can obtain one at http://mozilla.org/MPL/2.0/. + +from __future__ import absolute_import, print_function, unicode_literals + +import os +import sys + +from mach.decorators import ( + Command, + CommandArgument, + CommandProvider, +) + +import mozhttpd + +from mozbuild.base import MachCommandBase + + +@CommandProvider +class Documentation(MachCommandBase): + """Helps manage in-tree documentation.""" + + @Command('doc', category='devenv', + description='Generate and display documentation from the tree.') + @CommandArgument('what', nargs='*', metavar='DIRECTORY [, DIRECTORY]', + help='Path(s) to documentation to build and display.') + @CommandArgument('--format', default='html', + help='Documentation format to write.') + @CommandArgument('--outdir', default=None, metavar='DESTINATION', + help='Where to write output.') + @CommandArgument('--no-open', dest='auto_open', default=True, action='store_false', + help="Don't automatically open HTML docs in a browser.") + @CommandArgument('--http', const=':6666', metavar='ADDRESS', nargs='?', + help='Serve documentation on an HTTP server, e.g. ":6666".') + def build_docs(self, what=None, format=None, outdir=None, auto_open=True, http=None): + self._activate_virtualenv() + self.virtualenv_manager.install_pip_package('sphinx_rtd_theme==0.1.6') + + import sphinx + import webbrowser + + if not outdir: + outdir = os.path.join(self.topobjdir, 'docs') + if not what: + what = [os.path.join(self.topsrcdir, 'tools')] + outdir = os.path.join(outdir, format) + + generated = [] + failed = [] + for path in what: + path = os.path.normpath(os.path.abspath(path)) + docdir = self._find_doc_dir(path) + + if not docdir: + failed.append((path, 'could not find docs at this location')) + continue + + # find project name to use as a namespace within `outdir` + project = self._find_project_name(docdir) + savedir = os.path.join(outdir, project) + + args = [ + 'sphinx', + '-b', format, + docdir, + savedir, + ] + result = sphinx.build_main(args) + if result != 0: + failed.append((path, 'sphinx return code %d' % result)) + else: + generated.append(savedir) + + index_path = os.path.join(savedir, 'index.html') + if not http and auto_open and os.path.isfile(index_path): + webbrowser.open(index_path) + + if generated: + print('\nGenerated documentation:\n%s\n' % '\n'.join(generated)) + + if failed: + failed = ['%s: %s' % (f[0], f[1]) for f in failed] + return die('failed to generate documentation:\n%s' % '\n'.join(failed)) + + if http is not None: + host, port = http.split(':', 1) + addr = (host, int(port)) + if len(addr) != 2: + return die('invalid address: %s' % http) + + httpd = mozhttpd.MozHttpd(host=addr[0], port=addr[1], docroot=outdir) + print('listening on %s:%d' % addr) + httpd.start(block=True) + + def _find_project_name(self, path): + import imp + path = os.path.join(path, 'conf.py') + with open(path, 'r') as fh: + conf = imp.load_module('doc_conf', fh, path, + ('.py', 'r', imp.PY_SOURCE)) + + return conf.project.replace(' ', '_') + + def _find_doc_dir(self, path): + search_dirs = ('doc', 'docs') + for d in search_dirs: + p = os.path.join(path, d) + if os.path.isfile(os.path.join(p, 'conf.py')): + return p + + +def die(msg, exit_code=1): + msg = '%s: %s' % (sys.argv[0], msg) + print(msg, file=sys.stderr) + return exit_code diff --git a/tools/docs/moztreedocs/__init__.py b/tools/docs/moztreedocs/__init__.py new file mode 100644 index 000000000..a67edbded --- /dev/null +++ b/tools/docs/moztreedocs/__init__.py @@ -0,0 +1,126 @@ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, # You can obtain one at http://mozilla.org/MPL/2.0/. + +from __future__ import unicode_literals + +import os + +from mozbuild.frontend.reader import BuildReader +from mozpack.copier import FileCopier +from mozpack.files import FileFinder +from mozpack.manifests import InstallManifest + +import sphinx +import sphinx.apidoc + + +class SphinxManager(object): + """Manages the generation of Sphinx documentation for the tree.""" + + def __init__(self, topsrcdir, main_path, output_dir): + self._topsrcdir = topsrcdir + self._output_dir = output_dir + self._docs_dir = os.path.join(output_dir, '_staging') + self._conf_py_path = os.path.join(main_path, 'conf.py') + self._index_path = os.path.join(main_path, 'index.rst') + self._trees = {} + self._python_package_dirs = set() + + def read_build_config(self): + """Read the active build config and add docs to this instance.""" + + # Reading the Sphinx variables doesn't require a full build context. + # Only define the parts we need. + class fakeconfig(object): + def __init__(self, topsrcdir): + self.topsrcdir = topsrcdir + + config = fakeconfig(self._topsrcdir) + reader = BuildReader(config) + + for path, name, key, value in reader.find_sphinx_variables(): + reldir = os.path.dirname(path) + + if name == 'SPHINX_TREES': + assert key + self.add_tree(os.path.join(reldir, value), + os.path.join(reldir, key)) + + if name == 'SPHINX_PYTHON_PACKAGE_DIRS': + self.add_python_package_dir(os.path.join(reldir, value)) + + def add_tree(self, source_dir, dest_dir): + """Add a directory from where docs should be sourced.""" + if dest_dir in self._trees: + raise Exception('%s has already been registered as a destination.' + % dest_dir) + + self._trees[dest_dir] = source_dir + + def add_python_package_dir(self, source_dir): + """Add a directory containing Python packages. + + Added directories will have Python API docs generated automatically. + """ + self._python_package_dirs.add(source_dir) + + def generate_docs(self, app): + """Generate/stage documentation.""" + app.info('Reading Sphinx metadata from build configuration') + self.read_build_config() + app.info('Staging static documentation') + self._synchronize_docs() + app.info('Generating Python API documentation') + self._generate_python_api_docs() + + def _generate_python_api_docs(self): + """Generate Python API doc files.""" + out_dir = os.path.join(self._docs_dir, 'python') + base_args = ['sphinx', '--no-toc', '-o', out_dir] + + for p in sorted(self._python_package_dirs): + full = os.path.join(self._topsrcdir, p) + + finder = FileFinder(full, find_executables=False) + dirs = {os.path.dirname(f[0]) for f in finder.find('**')} + + excludes = {d for d in dirs if d.endswith('test')} + + args = list(base_args) + args.append(full) + args.extend(excludes) + + sphinx.apidoc.main(args) + + def _synchronize_docs(self): + m = InstallManifest() + + m.add_symlink(self._conf_py_path, 'conf.py') + + for dest, source in sorted(self._trees.items()): + source_dir = os.path.join(self._topsrcdir, source) + for root, dirs, files in os.walk(source_dir): + for f in files: + source_path = os.path.join(root, f) + rel_source = source_path[len(source_dir) + 1:] + + m.add_symlink(source_path, os.path.join(dest, rel_source)) + + copier = FileCopier() + m.populate_registry(copier) + copier.copy(self._docs_dir) + + with open(self._index_path, 'rb') as fh: + data = fh.read() + + indexes = ['%s/index' % p for p in sorted(self._trees.keys())] + indexes = '\n '.join(indexes) + + packages = [os.path.basename(p) for p in self._python_package_dirs] + packages = ['python/%s' % p for p in packages] + packages = '\n '.join(sorted(packages)) + data = data.format(indexes=indexes, python_packages=packages) + + with open(os.path.join(self._docs_dir, 'index.rst'), 'wb') as fh: + fh.write(data) -- cgit v1.2.3