Update the README.

1 files changed, 47 insertions, 9 deletions

diff --git a/docs/builder/README b/docs/builder/README
index 7e63cfd..bf9d7ad 100644
--- a/docs/builder/README
+++ b/docs/builder/README
@@ -2,7 +2,7 @@ RTEMS Documentation Web Site
 ============================
 
 Chris Johns <chrisj@rtems.org>
-20th March 2017
+ 13th Sep 2017
 
 The following documents the RTEMS documentation website.
 
@@ -30,7 +30,7 @@ Change to root to exec a shell in the jali:
  Password:
  root@service2:/home/chrisj # jexec 8 /bin/sh
  # su - chrisj
- \u@docs#
+ docs#
 
 Locations
 ---------
@@ -47,7 +47,7 @@ Website
 -------
 
 The website is held in the publically avaliable personal repo called
-`rtems-admin.git`. To update clone the repo:
+`rtems-admin.git`. To update the website clone the repo:
 
  # git clone git://git.rtems.org/chrisj/rtems-admin.git
 
@@ -160,13 +160,51 @@ machines.
 Building and Uploading
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The `rtems-docs-upload` is a top level script that loops in a shell with the
-SSH key added to an SSH agent. If a build has built any documentation it is
-uploaded to the RTEMS FTP server. The repo is checked every 10 minutes.
+The documentation is built on sync.rtems.org, a jail running on
+builder1.rtems.org.
 
-The `rtems-docs-build-branches` builds each branch that has changed and
+To build the documentation clone the RTEMS Administration repo:
+
+ # git clone git://git.rtems.org/chrisj/rtems-admin.git
+
+Change the documentation builder directory:
+
+ # cd rtems-admin/doc/builder
+
+The RTEMS documentation uses sphinx to build it and the best way to manage
+sphinx is to use a virtual environment. Create the virtualenv by:
+
+ # virtualenv docs_builder
+
+Activate the virtual environment:
+
+ # source docs_builder/bin/activate
+
+Install sphinx:
+
+ (docs_builder) # pip install sphinx
+ (docs_builder) # pip install sphinxcontrib-bibtex
+
+Finally deactivate the virtual environment:
+
+ (docs_builder) # deactivate
+
+Run a test build with:
+
+ # $PWD/rtems-docs-build-cron
+
+The built files will be placed in the handover directory on ftp.rtems.org. If
+there are any issues check `latest/build.log` for details.
+
+The cron job on the publishing machine runs two scripts. The first is
+`rtems-docs-build-branches`. It builds each branch that has changed and
 packages the changes into a tarball. It also generates a tag file containing
-the branch and hash for each branch in the package.
+the branch and hash for each branch in the package. The second script is
+`rtems-docs-upload`. It moves the tags file and built output to the FTP
+server's handover directory.
+
+Add `rtems-docs-build-cron` as a cron job every 5 minute, depending on the
+time it takes to build the documentation.
 
 Downloading and Publishing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -174,7 +212,7 @@ Downloading and Publishing
 The `rtems-docs-cron` is a top level script that runs every 5 minutes. It
 downloads then publishes any changes.
 
-The `rtems-docs-download` script fetches the tags file from the FTP server and
+The `rtems-docs-download` script copies the tags file from the FTP server and
 checks each tag again the tags currently published. If there is a difference in
 the file package is downloaeded and the branches unpacked.