Turn existing instruction material into documentation

.gitignore

@@ -16,3 +16,7 @@ dist/
 .coverage.*
 .pylint.d/
 .pytest_cache/
+
+# Documentation related things:
+docs/build/
+docs/source/api/

CONTRIBUTING.rst

-Contributing to BuildGrid
-=========================
-Some guidelines for people wanting to contribute. Also please always feel free to speak to us, we're very friendly :-)
+
+.. _contributing:
+
+Contributing
+============
+
+Some guidelines for people wanting to contribute. Also please always feel free
+to speak to us, we're very friendly :-)
 
 Feature Additions
 -----------------
@@ -157,7 +162,7 @@ Priority Labels
 For now, we only have 'High Priority', which indicates an urgent task. We may add more granularity if we get more contributors. 
 
 Status
-'''''
+''''''
 We have:
 
 * ToDo

README.rst

-BuildGrid
-=========
+
+.. _about:
+
+About
+=====
 
 .. image:: https://gitlab.com/Buildgrid/buildgrid/badges/master/pipeline.svg
    :target: https://gitlab.com/BuildStream/buildstream/commits/master
@@ -7,79 +10,38 @@ BuildGrid
 .. image:: https://gitlab.com/BuildGrid/buildgrid/badges/master/coverage.svg?job=coverage
    :target: https://gitlab.com/BuildGrid/buildgrid/commits/master
 
+BuildGrid is a Python remote execution service which implements Google's
+`Remote Execution API`_ and the `Remote Workers API`_. The project's goal is to
+be able to execute build jobs remotely on a grid of computers in order to
+massively speed up build times. Workers on the grid should be able to run with
+different environments. It is designed to work with but not exclusively
+`BuildStream`_.
 
-BuildGrid is a python remote execution service which implements the `Remote Execution API <https://github.com/bazelbuild/remote-apis//>`_ and the `Remote Workers API <https://docs.google.com/document/d/1s_AzRRD2mdyktKUj2HWBn99rMg_3tcPvdjx3MPbFidU/edit#heading=h.1u2taqr2h940/>`_.
-
-The goal is to be able to execute build jobs remotely on a grid of computers to massively speed up build times. Workers on the system will also be able to run with different environments. It is designed to work with but not exclusively with `BuildStream <https://wiki.gnome.org/Projects/BuildStream/>`_.
-
-Install
--------
-
-To install::
-
-   git clone https://gitlab.com/BuildGrid/buildgrid.git
-   cd buildgrid
-   pip3 install --user -e .
-
-This will install BuildGrid's python dependencies into your user’s homedir in ~/.local
-and will run BuildGrid directly from the git checkout. It is recommended you adjust
-your path with::
-
-  export PATH="${PATH}:${HOME}/.local/bin"
-
-Which you can add to the end of your `~/.bashrc`.
-
-Instructions for a Dummy Work
-----------------------
-
-In one terminal, start a server::
-
-  bgd server start
-
-In another terminal, send a request for work::
-
-  bgd execute request-dummy
-
-The stage should show as `QUEUED` as it awaits a bot to pick up the work::
-
-  bgd execute list
-
-Create a bot session::
-
-  bgd bot dummy
-
-Show the work as completed::
-
-  bgd execute list
-
-Instructions for a Simple Build
--------------------------------
-
-This example covers a simple build. The user will upload a directory containing a C file and a command to the CAS. The bot will then fetch the uploaded directory and command which will then be run inside a temporary directory. The result will then be uploaded to the CAS and downloaded by the user. This is an early demo and still lacks a few features such as symlink support and checking to see if files exist in the CAS before executing a command.
-
-Create a new directory called `test-buildgrid/` and place the following C file in it called `hello.c`::
-
-  #include <stdio.h>
-  int main()
-  {
-   printf("Hello, World!\n");
-   return 0;
-  }
+.. _Remote Execution API: https://github.com/bazelbuild/remote-apis
+.. _Remote Workers API: https://docs.google.com/document/d/1s_AzRRD2mdyktKUj2HWBn99rMg_3tcPvdjx3MPbFidU/edit#heading=h.1u2taqr2h940
+.. _BuildStream: https://wiki.gnome.org/Projects/BuildStream
 
-Now start a BuildGrid server, passing it a directory it can write a CAS to::
 
-  bgd server start --cas disk --cas-cache disk --cas-disk-directory /path/to/empty/directory
+.. _getting-started:
 
-Start the following bot session::
+Getting started
+---------------
 
-  bgd bot temp-directory
+Please refer to the `documentation`_ for `installation`_ and `usage`_
+instructions.
 
-Upload the directory containing the C file::
+.. _documentation: https://buildgrid.gitlab.io/buildgrid
+.. _installation: https://buildgrid.gitlab.io/buildgrid/installation.html
+.. _usage: https://buildgrid.gitlab.io/buildgrid/using.html
 
-  bgd cas upload-dir /path/to/test-buildgrid
 
-Now we send an execution request to the bot with the name of the epxected `output-file`, a boolean describing if it is executeable, the path to the directory we uploaded in order to calculate the digest and finally the command to run on the bot::
+.. _about-resources:
 
-  bgd execute command --output-file hello True /path/to/test-buildgrid -- gcc -Wall hello.c -o hello
+Resources
+---------
 
-The resulting executeable should have returned to a new directory called `testing/`
+- Homepage: https://buildgrid.build
+- GitLab repository: https://gitlab.com/BuildGrid/buildgrid
+- Bug tracking: https://gitlab.com/BuildGrid/buildgrid/issues
+- Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
+- IRC channel: irc://chat.freenode.net/#buildgrid

docs/source/about.rst

+.. include:: ../../README.rst
\ No newline at end of file

docs/source/contributing.rst

+.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file

docs/source/index.rst

@@ -3,19 +3,28 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+
 BuildGrid's documentation
 =========================
 
+Remote execution service implementing Google's REAPI and RWAPI.
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
+   about.rst
+   installation.rst
+   using.rst
+   reference.rst
+   contributing.rst
+
 
 Resources
 ---------
 
-* Homepage: https://buildgrid.build
-* GitLab repository: https://gitlab.com/BuildGrid/buildgrid
-* Bug Tracking: https://gitlab.com/BuildGrid/buildgrid/issues
-* Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
-* IRC Channel: irc://chat.freenode.net/#buildgrid
+- Homepage: https://buildgrid.build
+- GitLab repository: https://gitlab.com/BuildGrid/buildgrid
+- Bug tracking: https://gitlab.com/BuildGrid/buildgrid/issues
+- Mailing list: https://lists.buildgrid.build/cgi-bin/mailman/listinfo/buildgrid
+- IRC channel: irc://chat.freenode.net/#buildgrid

docs/source/installation.rst

+
+.. _installation:
+
+Installation
+============
+
+How to install BuildGrid onto your machine.
+
+To install:
+
+.. code-block:: sh
+
+   git clone https://gitlab.com/BuildGrid/buildgrid.git
+   cd buildgrid
+   pip3 install --user -e .
+
+This will install BuildGrid's python dependencies into your user’s homedir in ~/.local
+and will run BuildGrid directly from the git checkout. It is recommended you adjust
+your path with:
+
+.. code-block:: sh
+
+   export PATH="${PATH}:${HOME}/.local/bin"
+
+Which you can add to the end of your `~/.bashrc`.

docs/source/reference.rst

+
+.. _reference:
+
+Reference
+=========
+
+This section contains BuildGrid API and CLI reference documentation.
+
+.. toctree::
+   :maxdepth: 2
+
+   reference_api.rst
+   reference_cli.rst

docs/source/reference_api.rst

+
+.. _api_reference:
+
+API reference
+=============
+
+BuildGrid's Application Programming Interface (API) reference documentation.

docs/source/reference_cli.rst

+
+.. _cli_reference:
+
+CLI reference
+=============
+
+BuildGrid's Command Line Interface (CLI) reference documentation.

docs/source/using.rst

+
+.. _using:
+
+Using
+=====
+
+This section covers how to run an use the BuildGrid build service.
+
+.. toctree::
+   :maxdepth: 2
+
+   using_dummy_build.rst
+   using_simple_build.rst

docs/source/using_dummy_build.rst

+
+.. _dummy-build:
+
+Dummy build
+===========
+
+In one terminal, start a server:
+
+.. code-block:: sh
+
+   bgd server start
+
+In another terminal, send a request for work:
+
+.. code-block:: sh
+
+   bgd execute request-dummy
+
+The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
+
+.. code-block:: sh
+
+   bgd execute list
+
+Create a bot session:
+
+.. code-block:: sh
+
+   bgd bot dummy
+
+Show the work as completed:
+
+.. code-block:: sh
+
+   bgd execute list

docs/source/using_simple_build.rst

+
+.. _simple-build:
+
+Simple build
+============
+
+This example covers a simple build. The user will upload a directory containing
+a C file and a command to the CAS. The bot will then fetch the uploaded
+directory and command which will then be run inside a temporary directory. The
+result will then be uploaded to the CAS and downloaded by the user. This is an
+early demo and still lacks a few features such as symlink support and checking
+to see if files exist in the CAS before executing a command.
+
+Create a new directory called `test-buildgrid/` and place the following C file
+in it called `hello.c`:
+
+.. code-block:: C
+
+   #include <stdio.h>
+   int main()
+   {
+     printf("Hello, World!\n");
+     return 0;
+   }
+
+Now start a BuildGrid server, passing it a directory it can write a CAS to:
+
+.. code-block:: sh
+
+   bgd server start --cas disk --cas-cache disk --cas-disk-directory /path/to/empty/directory
+
+Start the following bot session:
+
+.. code-block:: sh
+
+   bgd bot temp-directory
+
+Upload the directory containing the C file:
+
+.. code-block:: sh
+
+   bgd cas upload-dir /path/to/test-buildgrid
+
+Now we send an execution request to the bot with the name of the epxected
+``output-file``, a boolean describing if it is executeable, the path to the
+directory we uploaded in order to calculate the digest and finally the command
+to run on the bot:
+
+.. code-block:: sh
+
+   bgd execute command --output-file hello True /path/to/test-buildgrid -- gcc -Wall hello.c -o hello
+
+The resulting executeable should have returned to a new directory called
+``testing``.