From 52a117cab8a876594d635a7a35b2b5e058ed8c91 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 14 Sep 2017 02:34:45 +0000 Subject: Update the README. --- docs/builder/README | 56 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file 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 -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. -- cgit v1.2.3