Bug 1518586 - [mach] Add some basic usage docs r=nalexander
authorAndrew Halberstadt <ahalberstadt@mozilla.com>
Fri, 11 Jan 2019 03:34:30 +0000
changeset 513485 5b651dea28d8
parent 513484 696de1cfcb5e
child 513486 729ea50e3045
push id1953
push userffxbld-merge
push dateMon, 11 Mar 2019 12:10:20 +0000
treeherdermozilla-release@9c35dcbaa899 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersnalexander
bugs1518586
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1518586 - [mach] Add some basic usage docs r=nalexander I was looking for a good place to put documentation for enabling the bash completion script when I realized that the 'mach' documentation is targeted at tool developers rather than users. Seeing as this is the main 'mach' documentation and we want to make 'firefox-source-docs' the place to go for contribution information, we should endeavour to target end users with this documentation. This adds a very basic usage page which should be expanded upon, but is better than nothing. I changed the headers in 'index.rst' to use raw:: html so that they don't show up in the nav bar to the left (and subsequently block the *actually important* things from appearing). Differential Revision: https://phabricator.services.mozilla.com/D16254
python/mach/docs/index.rst
python/mach/docs/usage.rst
--- a/python/mach/docs/index.rst
+++ b/python/mach/docs/index.rst
@@ -1,22 +1,25 @@
 ====
-mach
+Mach
 ====
 
 Mach (German for *do*) is a generic command dispatcher for the command
 line.
 
 To use mach, you install the mach core (a Python package), create an
 executable *driver* script (named whatever you want), and write mach
 commands. When the *driver* is executed, mach dispatches to the
 requested command handler automatically.
 
-Features
-========
+.. raw:: html
+
+    <h2>Features</h2>
+
+----
 
 On a high level, mach is similar to using argparse with subparsers (for
 command handling). When you dig deeper, mach offers a number of
 additional features:
 
 Distributed command definitions
   With optparse/argparse, you have to define your commands on a central
   parser instance. With mach, you annotate your command methods with
@@ -29,18 +32,21 @@ Command categories
 Logging management
   Mach provides a facility for logging (both classical text and
   structured) that is available to any command handler.
 
 Settings files
   Mach provides a facility for reading settings from an ini-like file
   format.
 
-Components
-==========
+.. raw:: html
+
+    <h2>Components</h2>
+
+----
 
 Mach is conceptually composed of the following components:
 
 core
   The mach core is the core code powering mach. This is a Python package
   that contains all the business logic that makes mach work. The mach
   core is common to all mach deployments.
 
@@ -51,25 +57,30 @@ commands
 
 driver
   The *driver* is the entry-point to mach. It is simply an executable
   script that loads the mach core, tells it where commands can be found,
   then asks the mach core to handle the current request. The driver is
   unique to the deployed environment. But, it's usually based on an
   example from this source tree.
 
-Project State
-=============
+.. raw:: html
+
+    <h2> Project State</h2>
+
+----
 
 mach was originally written as a command dispatching framework to aid
 Firefox development. While the code is mostly generic, there are still
 some pieces that closely tie it to Mozilla/Firefox. The goal is for
 these to eventually be removed and replaced with generic features so
 mach is suitable for anybody to use. Until then, mach may not be the
 best fit for you.
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
+   usage
    commands
    driver
    logging
    settings
new file mode 100644
--- /dev/null
+++ b/python/mach/docs/usage.rst
@@ -0,0 +1,94 @@
+.. _mach_usage:
+
+==========
+User Guide
+==========
+
+Mach is the central entry point for most operations that can be performed in
+mozilla-central.
+
+
+Command Help
+------------
+
+To see an overview of all the available commands, run:
+
+.. code-block:: shell
+
+    $ ./mach help
+
+For more detailed information on a specific command, run:
+
+.. code-block:: shell
+
+    $ ./mach help <command>
+
+If a command has subcommands listed, you can see more details on the subcommand
+by running:
+
+.. code-block:: shell
+
+    $ ./mach help <command> <subcommand>
+
+Alternatively, you can pass ``-h/--help``. For example, all of the
+following are valid:
+
+.. code-block:: shell
+
+    $ ./mach help try
+    $ ./mach help try fuzzy
+    $ ./mach try -h
+    $ ./mach try fuzzy --help
+
+
+Auto Completion
+---------------
+
+A `bash completion`_ script is bundled with mach. To enable it with ``bash``,
+add the following to your ``~/.bashrc``, ``~/.bash_profile`` or equivalent:
+
+.. code-block:: shell
+
+    source <srcdir>/python/mach/bash-completion.sh
+
+This script can also be used with ``zsh``. Add this to your ``~/.zshrc`` or
+equivalent:
+
+.. code-block:: shell
+
+    autoload bashcompinit
+    bashcompinit
+    source <srcdir>/python/mach/bash-completion.sh
+
+Don't forget to substitute ``<srcdir>`` with the path to your checkout.
+
+
+User Settings
+-------------
+
+Some mach commands can read configuration from a ``machrc`` file. The default
+location for this file is ``~/.mozbuild/machrc`` (you'll need to create it).
+This can also be set to a different location by setting the ``MACHRC``
+environment variable.
+
+For a list of all the available settings, run:
+
+.. code-block:: shell
+
+    $ ./mach settings
+
+The settings file follows the ``ini`` format, e.g:
+
+.. code-block:: ini
+
+    [alias]
+    eslint = lint -l eslint
+
+    [build]
+    telemetry = true
+
+    [try]
+    default = fuzzy
+
+
+.. _bash completion: https://searchfox.org/mozilla-central/source/python/mach/bash-completion.sh