Documentation/contributor/website-work.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @node Website work
   3 @chapter Website work
   4
   5 @menu
   6 * Introduction to website work::
   7 * Uploading and security::
   8 * Translating the website::
   9 @end menu
  10
  11
  12 @node Introduction to website work
  13 @section Introduction to website work
  14
  15 The website is @emph{not} written directly in HTML;
  16 instead, the source is Texinfo, which is then generated into HTML,
  17 PDF, and Info formats.  The sources are
  18
  19 @verbatim
  20 Documentation/web.texi
  21 Documentation/web/*.texi
  22 @end verbatim
  23
  24 Unless otherwise specified, follow the instructions and policies
  25 given in @ref{Documentation work}.  That chapter also contains a
  26 quick introduction to Texinfo; consulting an external Texinfo
  27 manual should be not necessary.
  28
  29 @subheading Exceptions to the documentation policies
  30
  31 @itemize
  32
  33 @item
  34 Sectioning: the website only uses chapters and sections; no
  35 subsections or subsubsections.
  36
  37 @item
  38 @@ref@{@}s to other manuals (@@ruser, @@rlearning, etc): you can't
  39 link to any pieces of automatically generated documentation, like
  40 the IR or certain NR appendices.
  41
  42 @dots{}
  43
  44 @item
  45 For anything not listed here, just follow the same style as the
  46 existing texinfo files.
  47
  48 @end itemize
  49
  50
  51 @node Uploading and security
  52 @section Uploading and security
  53
  54 The website is generated hourly by user @code{graham} the host
  55 @code{lilypond.org}.  For security reasons, we do not use the
  56 makefiles and scripts directly from git; copies of the relevant
  57 scripts are examined and copied to
  58 @code{~graham/lilypond/trusted-scripts/}
  59
  60 Get latest source code:
  61
  62 @verbatim
  63 ### update-git.sh
  64 #!/bin/sh
  65 cd $HOME/src/lilypond
  66 git fetch origin
  67 git merge origin/master
  68 @end verbatim
  69
  70 Check for any updates to trusted scripts / files:
  71
  72 @verbatim
  73 ### check-git.sh
  74 #!/bin/sh
  75 GIT=$HOME/src/lilypond
  76 DEST=$HOME/lilypond/trusted-scripts
  77 diff -u $DEST/website.make $GIT/website.make
  78 diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
  79 diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
  80 diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
  81 diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
  82 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
  83 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
  84 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
  85 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
  86 @end verbatim
  87
  88 If the changes look ok, make them trusted:
  89
  90 @verbatim
  91 ### copy-from-git.sh
  92 #!/bin/sh
  93 GIT=$HOME/src/lilypond
  94 DEST=$HOME/lilypond/trusted-scripts
  95 cp $GIT/website.make $DEST/website.make
  96 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
  97 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
  98 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
  99 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
 100 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
 101 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
 102 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
 103 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
 104 @end verbatim
 105
 106 Build the website:
 107
 108 @verbatim
 109 ### make-website.sh
 110 #!/bin/sh
 111 DEST=$HOME/web/
 112 cd $HOME/src/build-website
 113 cp $HOME/lilypond/trusted-scripts/website.make .
 114
 115 make -f website.make WEBSITE_ONLY_BUILD=1 website
 116 rsync -ra $HOME/src/build-website/out-website/website/ $DEST/website/
 117 cp $HOME/src/build-website/out-website/pictures $DEST
 118 cp $HOME/src/build-website/out-website/.htaccess $DEST
 119 @end verbatim
 120
 121 Cronjob to automate the trusted portions:
 122
 123 @verbatim
 124 # website-rebuild.cron
 125 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
 126 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
 127 @end verbatim
 128
 129
 130 To reduce the CPU burden on the shared host (as well as some
 131 security concerns), the @file{Documentation/pictures/} and
 132 @file{Documentation/web/ly-examples/} directories are @strong{not}
 133 compiled.  If you modify any files in those directories, a user in
 134 the @code{lilypond} group must upload them to @file{~graham/media}
 135 on the host.
 136
 137 Upload latest pictures/ and ly-examples/ (local script):
 138
 139 @verbatim
 140 ### upload-lily-web-media.sh
 141 #!/bin/sh
 142 BUILD_DIR=$HOME/src/build-lilypond
 143
 144 PICS=$BUILD_DIR/Documentation/pictures/out-www/
 145 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
 146
 147 cd $BUILD_DIR
 148 rsync -a $PICS graham@lilypond.org:media/pictures
 149 rsync -a $EXAMPLES graham@lilypond.org:ly-examples
 150 @end verbatim
 151
 152
 153 @node Translating the website
 154 @section Translating the website
 155
 156 As it has much more audience, the website should be translated before
 157 the documentation; see @ref{Translating the documentation}.