Bug 917988 - Sphinx managed build system documentation; add mach build-docs; r=bsmedberg

--HG--
rename : python/mozbuild/dumbmake/README.rst => build/docs/mozbuild/dumbmake.rst
rename : python/mozbuild/mozbuild/frontend/README.rst => build/docs/mozbuild/frontend.rst
rename : python/mozbuild/README.rst => build/docs/mozbuild/index.rst

build/docs/conf.py

@@ -0,0 +1,49 @@
+# 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
+
+from datetime import datetime
+
+
+here = os.path.abspath(os.path.dirname(__file__))
+mozilla_dir = os.path.normpath(os.path.join(here, '..', '..'))
+
+import mdn_theme
+
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+project = u'Mozilla Build System'
+year = datetime.now().year
+copyright = u'%s, Mozilla Foundation, CC BY-SA 3.0' % year
+
+# Grab the version from the source tree's milestone.
+with open(os.path.join(mozilla_dir, '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']
+pygments_style = 'sphinx'
+
+html_theme_path = [mdn_theme.get_theme_dir()]
+html_theme = 'mdn'
+
+html_static_path = ['_static']
+htmlhelp_basename = 'MozillaBuildSystemdoc'

build/docs/glossary.rst

@@ -0,0 +1,28 @@
+========
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   object directory
+       A directory holding the output of the build system. The build
+       system attempts to isolate all file modifications to this
+       directory. By convention, object directories are commonly
+       directories under the source directory prefixed with **obj-**.
+       e.g. **obj-firefox**.
+
+   mozconfig
+       A shell script used to configure the build system.
+
+   configure
+       A generated shell script which detects the current system
+       environment, applies a requested set of build configuration
+       options, and writes out metadata to be consumed by the build
+       system.
+
+   config.status
+       An executable file produced by **configure** that takes the
+       generated build config and writes out files used to build the
+       tree. Traditionally, config.status writes out a bunch of
+       Makefiles.

build/docs/index.rst

@@ -0,0 +1,41 @@
+==================================
+Mozilla Build System Documentation
+==================================
+
+Overview
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   glossary
+
+Important Concepts
+==================
+.. toctree::
+   :maxdepth: 1
+
+   Mozconfig Files <mozconfigs>
+   Profile Guided Optimization <pgo>
+
+mozbuild
+========
+
+mozbuild is a Python package containing a lot of the code for the
+Mozilla build system.
+
+.. toctree::
+   :maxdepth: 1
+
+   mozbuild/index
+   mozbuild/frontend
+   mozbuild/dumbmake
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

build/docs/mozconfigs.rst

@@ -0,0 +1,68 @@
+===============
+mozconfig Files
+===============
+
+mozconfig files are used to configure how a build works.
+
+mozconfig files are actually shell scripts. They are executed in a
+special context with specific variables and functions exposed to them.
+
+API
+===
+
+Functions
+---------
+
+The following special functions are available to a mozconfig script.
+
+ac_add_options
+^^^^^^^^^^^^^^
+
+This function is used to declare extra options/arguments to pass into
+configure.
+
+e.g.::
+
+    ac_add_options --disable-tests
+    ac_add_options --enable-optimize
+
+mk_add_options
+^^^^^^^^^^^^^^
+
+This function is used to inject statements into client.mk for execution.
+It is typically used to define variables, notably the object directory.
+
+e.g.::
+
+    mk_add_options AUTOCLOBBER=1
+
+ac_add_options
+^^^^^^^^^^^^^^
+
+This is a variant of ac_add_options() which only adds configure options
+for a specified application. This is only used when building multiple
+applications through client.mk. This function is typically not needed.
+
+Special mk_add_options Variables
+--------------------------------
+
+For historical reasons, the method for communicating certain
+well-defined variables is via mk_add_options(). In this section, we
+document what those special variables are.
+
+MOZ_OBJDIR
+^^^^^^^^^^
+
+This variable is used to define the :term:`object directory` for the current
+build.
+
+Finding the active mozconfig
+============================
+
+Multiple mozconfig files can exist to provide different configuration
+options for different tasks. The rules for finding the active mozconfig
+are defined in the
+:py:func:`mozbuild.mozconfig.MozconfigLoader.find_mozconfig` method:
+
+.. autoclass:: mozbuild.mozconfig.MozconfigLoader
+   :members: find_mozconfig

build/docs/pgo.rst

@@ -0,0 +1,40 @@
+.. _pgo:
+
+===========================
+Profile Guided Optimization
+===========================
+
+:abbr:`PGO (Profile Guided Optimization)` is the process of adding
+probes to a compiled binary, running said binary, then using the
+run-time information to *recompile* the binary to (hopefully) make it
+faster.
+
+How PGO Builds Work
+===================
+
+The supported interface for invoking a PGO build is to evaluate the
+*build* target of client.mk with *MOZ_PGO* defined. e.g.::
+
+    $ make -f client.mk MOZ_PGO=1
+
+This is equivalent to::
+
+    $ make -f client.mk profiledbuild
+
+Which is roughly equivalent to:
+
+#. Perform a build with *MOZ_PROFILE_GENERATE=1* and *MOZ_PGO_INSTRUMENTED=1*
+#. Package with *MOZ_PGO_INSTRUMENTED=1*
+#. Performing a run of the instrumented binaries
+#. $ make maybe_clobber_profiledbuild
+#. Perform a build with *MOZ_PROFILE_USE=1*
+
+Differences between toolchains
+==============================
+
+There are some implementation differences depending on the compiler
+toolchain being used.
+
+The *maybe_clobber_profiledbuild* step gets its name because of a
+difference. On Windows, this step merely moves some *.pgc* files around.
+Using GCC or Clang, it is equivalent to a *make clean*.

python/mozbuild/mozbuild/mach_commands.py

@@ -913,3 +913,37 @@ class MachDebug(object):
                 print('config defines:')
                 for k in sorted(config.defines):
                     print('\t%s' % k)
+
+
+@CommandProvider
+class Documentation(MachCommandBase):
+    """Helps manage in-tree documentation."""
+
+    @Command('build-docs', category='build-dev',
+        description='Generate documentation for the tree.')
+    @CommandArgument('--format', default='html',
+        help='Documentation format to write.')
+    @CommandArgument('outdir', default='<DEFAULT>', nargs='?',
+        help='Where to write output.')
+    def build_docs(self, format=None, outdir=None):
+        self._activate_virtualenv()
+
+        self.virtualenv_manager.install_pip_package('mdn-sphinx-theme==0.3')
+
+        import sphinx
+
+        if outdir == '<DEFAULT>':
+            outdir = os.path.join(self.topobjdir, 'docs', format)
+
+        args = [
+            sys.argv[0],
+            '-b', format,
+            os.path.join(self.topsrcdir, 'build', 'docs'),
+            outdir,
+        ]
+
+        result = sphinx.main(args)
+
+        print('Docs written to %s.' % outdir)
+
+        return result