Bug 1245953 - Convert TaskCluster docs to Sphinx; r=garndt
authorGregory Szorc <gps@mozilla.com>
Wed, 17 Feb 2016 10:24:06 -0800
changeset 284623 547e0c23071ebab8bde38d7ec354dff3a4dacdad
parent 284622 7b676d94c9dd9f63491fa5683dd433e955d14404
child 284624 623765c2381e49126a9768ba2f597edec7763ee6
push id30008
push usercbook@mozilla.com
push dateThu, 18 Feb 2016 11:01:39 +0000
treeherdermozilla-central@1150ac4755c7 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgarndt
bugs1245953
milestone47.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 1245953 - Convert TaskCluster docs to Sphinx; r=garndt It is possible to hook up in-tree documentation to Sphinx. Convert the one-off README.md to ReStructuredText and add it to the Sphinx docs. I added a moz.build file under testing/ because I don't think it is appropriate for the Sphinx directive to live in the root moz.build file. MozReview-Commit-ID: 90tCb7mA63C
moz.build
testing/moz.build
testing/taskcluster/README.md
testing/taskcluster/docs/index.rst
--- a/moz.build
+++ b/moz.build
@@ -16,16 +16,17 @@ CONFIGURE_SUBST_FILES += [
 ]
 
 if CONFIG['ENABLE_CLANG_PLUGIN']:
     DIRS += ['build/clang-plugin']
 
 DIRS += [
     'config',
     'python',
+    'testing',
 ]
 
 if not CONFIG['JS_STANDALONE']:
     CONFIGURE_SUBST_FILES += [
         'tools/update-packaging/Makefile',
     ]
     CONFIGURE_DEFINE_FILES += [
         'mozilla-config.h',
new file mode 100644
--- /dev/null
+++ b/testing/moz.build
@@ -0,0 +1,7 @@
+# -*- Mode: python; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 40 -*-
+# vim: set filetype=python:
+# 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/.
+
+SPHINX_TREES['taskcluster'] = 'taskcluster/docs'
\ No newline at end of file
rename from testing/taskcluster/README.md
rename to testing/taskcluster/docs/index.rst
--- a/testing/taskcluster/README.md
+++ b/testing/taskcluster/docs/index.rst
@@ -1,161 +1,176 @@
-# Taskcluster + Gecko Integration
+.. taskcluster_index:
+
+======================
+TaskCluster Automation
+======================
 
-## Directory structure:
+Directory structure
+===================
 
-  - tasks/  : All task definitions
+tasks/
+   All task definitions
 
-  - tests/  : Tests for the mach target internals related to task graph
-              generation
+tests/
+   Tests for the mach target internals related to task graph
+   generation
 
-  - scripts : Various scripts used by taskcluster docker images and
-              utilities these exist in tree primarily to avoid rebuilding
-              docker images.
+scripts/
+   Various scripts used by taskcluster docker images and
+   utilities these exist in tree primarily to avoid rebuilding
+   docker images.
 
-## Task conventions
+Task Conventions
+================
 
 In order to properly enable task reuse there are a small number of
 conventions and parameters that are specialized for build tasks vs test
 tasks. The goal here should be to provide as much of the power as
 taskcluster but not at the cost of making it easy to support the current
 model of build/test.
 
-
 All tasks are in the YAML format and are also processed via mustache to
 allow for greater customizations. All tasks have the following
 templates variables:
 
-
-  - `docker_image`: Helper for always using the latest version of a docker
-    image that exist in tree.
+``docker_image``
+----------------
+Helper for always using the latest version of a docker image that exist
+in tree::
 
-    ```
-    {{#docker_image}}base{{/docker_image}}
-    ```
-
-    Will produce something like (see the docker folder):
-
-    ```
-    quay.io/mozilla.com/base:0.11
-    ```
+   {{#docker_image}}base{{/docker_image}}
 
-  - `from_now`: Helper for crafting a JSON date in the future.
+Will produce something like (see the docker folder):
 
-    ```
-    {{#from_now}}1 year{{/from_now}}
-    ```
+   quay.io/mozilla.com/base:0.11
+
 
-    Will produce:
+``from_now``
+------------
 
-    ```
-    2014-10-19T22:45:45.655Z
-    ```
-
-  - `now`: Current time as a json formatted date.
+Helper for crafting a JSON date in the future.::
 
 
-### Build tasks
+   {{#from_now}}1 year{{/from_now}}
+
+Will produce::
+
+   2014-10-19T22:45:45.655Z
+
+
+``now``
+-------
 
-By convention build tasks are stored in `tasks/builds/` the location of
-each particular type of build is specified in `job_flags.yml` (and more
+Current time as a json formatted date.
+
+Build tasks
+===========
+
+By convention build tasks are stored in ``tasks/builds/`` the location of
+each particular type of build is specified in ``job_flags.yml`` (and more
 locations in the future), which is located in the appropriate subdirectory
-of `branches/`.
+of ``branches/``.
 
-#### Task format
+Task format
+-----------
 
 To facilitate better reuse of tasks there are some expectations of the
 build tasks. These are required for the test tasks to interact with the
 builds correctly but may not effect the builds or indexing services.
 
-```yaml
+.. code-block:: yaml
 
-# This is an example of just the special fields. Other fields that are
-# required by taskcluster are omitted and documented on http://docs.taskcluster.net/
-task:
+    # This is an example of just the special fields. Other fields that are
+    # required by taskcluster are omitted and documented on http://docs.taskcluster.net/
+    task:
 
-  payload:
-    # Builders usually create at least two important artifacts the build
-    # and the tests these can be anywhere in the task and also may have
-    # different path names to include things like arch and extension
-    artifacts:
-      # The build this can be anything as long as its referenced in
-      # locations.
-      'public/name_i_made_up.tar.gz': '/path/to/build'
-      'public/some_tests.zip': '/path/to/tests'
+      payload:
+        # Builders usually create at least two important artifacts the build
+        # and the tests these can be anywhere in the task and also may have
+        # different path names to include things like arch and extension
+        artifacts:
+          # The build this can be anything as long as its referenced in
+          # locations.
+          'public/name_i_made_up.tar.gz': '/path/to/build'
+          'public/some_tests.zip': '/path/to/tests'
 
-  extra:
-    # Build tasks may put their artifacts anywhere but there are common
-    # resources that test tasks need to do their job correctly so we
-    # need to provide an easy way to lookup the correct aritfact path.
-    locations:
-      build: 'public/name_i_made_up.tar.gz'
-      tests: 'public/some_tests.zip' or test_packages: 'public/test_packages.json'
-```
+      extra:
+        # Build tasks may put their artifacts anywhere but there are common
+        # resources that test tasks need to do their job correctly so we
+        # need to provide an easy way to lookup the correct aritfact path.
+        locations:
+          build: 'public/name_i_made_up.tar.gz'
+          tests: 'public/some_tests.zip' or test_packages: 'public/test_packages.json'
 
-#### Templates properties
+
+Templates properties
+--------------------
 
-  - repository: Target HG repository (ex:
-    https://hg.mozilla.org/mozilla-central)
+``repository``
+   Target HG repository (e.g.: ``https://hg.mozilla.org/mozilla-central``)
 
-  - revision: Target HG revision for gecko
+``revision``
+   Target HG revision for gecko
 
-  - owner: Email address of the committer
+``owner``
+   Email address of the committer
 
-### Test Tasks
+Test Tasks
+==========
 
-By convention test tasks are stored in `tasks/tests/` the location of
-each particular type of build is specified in `job_flags.yml` (and more
+By convention test tasks are stored in ``tasks/tests/`` the location of
+each particular type of build is specified in ``job_flags.yml`` (and more
 locations in the future)
 
+Template properties
+-------------------
 
-#### Template properties
+repository
+   Target HG repository (e.g.: ``https://hg.mozilla.org/mozilla-central``)
 
-  - repository: Target HG repository (ex:
-    https://hg.mozilla.org/mozilla-central)
+revision
+   Target HG revision for gecko
 
-  - revision: Target HG revision for gecko
-
-  - owner: Email address of the committer
+owner
+   Email address of the committer
 
-  - build_url: Location of the build
+build_url
+   Location of the build
 
-  - tests_url: Location of the tests.zip package
+tests_url
+   Location of the tests.zip package
 
-  - chunk: Current chunk
+chunk
+   Current chunk
 
-  - total_chunks: Total number of chunks
+total_chunks
+   Total number of chunks
 
-## Developing
+Developing
+==========
 
 Running commands via mach is the best way to invoke commands testing
 works a little differently (I have not figured out how to invoke
-python-test without running install steps first)
+python-test without running install steps first)::
 
+   mach python-test tests/
 
-```sh
-mach python-test tests/
-```
+Examples
+--------
 
-## Examples:
-
-Requires [taskcluster-cli](https://github.com/taskcluster/taskcluster-cli).
+Requires `taskcluster-cli <https://github.com/taskcluster/taskcluster-cli>`_::
 
-```sh
-mach taskcluster-trygraph --message 'try: -b do -p all' \
- --head-rev=33c0181c4a25 \
- --head-repository=http://hg.mozilla.org/mozilla-central \
- --owner=jlal@mozilla.com | taskcluster run-graph
-```
+    mach taskcluster-trygraph --message 'try: -b do -p all' \
+     --head-rev=33c0181c4a25 \
+     --head-repository=http://hg.mozilla.org/mozilla-central \
+     --owner=jlal@mozilla.com | taskcluster run-graph
 
-Creating only a build task and submitting to taskcluster:
+Creating only a build task and submitting to taskcluster::
 
-```sh
-mach taskcluster-build \
-  --head-revision=33c0181c4a25 \
-  --head-repository=http://hg.mozilla.org/mozilla-central \
-  --owner=user@domain.com tasks/builds/b2g_desktop.yml | taskcluster run-task --verbose
-```
+    mach taskcluster-build \
+      --head-revision=33c0181c4a25 \
+      --head-repository=http://hg.mozilla.org/mozilla-central \
+      --owner=user@domain.com tasks/builds/b2g_desktop.yml | taskcluster run-task --verbose
 
-```sh
-mach taskcluster-tests --task-id=Mcnvz7wUR_SEMhmWb7cGdQ  \
-  --owner=user@domain.com tasks/tests/b2g_mochitest.yml | taskcluster run-task --verbose
-```
+    mach taskcluster-tests --task-id=Mcnvz7wUR_SEMhmWb7cGdQ  \
+     --owner=user@domain.com tasks/tests/b2g_mochitest.yml | taskcluster run-task --verbose
+