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 * Debugging website and docs locally::
   9 * Translating the website::
  10 @end menu
  11
  12
  13 @node Introduction to website work
  14 @section Introduction to website work
  15
  16 The website is @emph{not} written directly in HTML;
  17 instead, the source is Texinfo, which is then generated into HTML,
  18 PDF, and Info formats.  The sources are
  19
  20 @example
  21 Documentation/web.texi
  22 Documentation/web/*.texi
  23 @end example
  24
  25 Unless otherwise specified, follow the instructions and policies
  26 given in @ref{Documentation work}.  That chapter also contains a
  27 quick introduction to Texinfo; consulting an external Texinfo
  28 manual should be not necessary.
  29
  30 @subheading Exceptions to the documentation policies
  31
  32 @itemize
  33
  34 @item
  35 Sectioning: the website only uses chapters and sections; no
  36 subsections or subsubsections.
  37
  38 @item
  39 @@ref@{@}s to other manuals (@@ruser, @@rlearning, etc): you can't
  40 link to any pieces of automatically generated documentation, like
  41 the IR or certain NR appendices.
  42
  43 @item
  44 The bibliography in Community->Publications is generated automatically
  45 from @file{@/.bib} files; formatting is done automatically by
  46 @file{texi@/-web@/.bst}.
  47
  48 @item
  49 @dots{}
  50
  51 @item
  52 For anything not listed here, just follow the same style as the
  53 existing website texinfo files.
  54
  55 @end itemize
  56
  57
  58 @node Uploading and security
  59 @section Uploading and security
  60
  61 The website is generated hourly by user @code{graham} the host
  62 @code{lilypond.org}.  For security reasons, we do not use the
  63 makefiles and scripts directly from git; copies of the relevant
  64 scripts are examined and copied to
  65 @code{~graham/lilypond/trusted-scripts/}
  66
  67 @subheading Initial setup
  68
  69 You should symlink your own @file{@/~/lilypond/} to
  70 @file{@/~graham/@/lilypond/}
  71
  72 If this directory does not exist, make it.  Git master should go
  73 in @file{@/~/lilypond/@/lilypond@/-git/} but make sure you enable:
  74
  75 @example
  76 git config core.filemode false
  77 @end example
  78
  79 If you have created any files in @file{@/~graham/@/lilypond/} then
  80 please run:
  81
  82 @example
  83 chgrp lilypond ~graham/lilypond/ -R
  84 chmod 775 ~graham/lilypond/ -R
  85 @end example
  86
  87 To reduce the CPU burden on the shared host (as well as some
  88 security concerns), the @file{Documentation/@/pictures/} and
  89 @file{Documentation/@/web/@/ly@/-examples/} directories are
  90 @strong{not} compiled.  You need to upload them, and if they ever
  91 change, a user in the @code{lilypond} group must upload them to
  92 @file{@/~graham/@/lilypond@/media} on the host.
  93
  94 Upload latest pictures/ and ly-examples/ (local script):
  95
  96 @warning{You may need to change a number of items in the below
  97 script.}
  98
  99 @verbatim
 100 ### upload-lily-web-media.sh
 101 #!/bin/sh
 102 BUILD_DIR=$HOME/src/build-lilypond
 103
 104 PICS=$BUILD_DIR/Documentation/pictures/out-www/
 105 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
 106
 107 cd $BUILD_DIR
 108 rsync -a $PICS graham@lilypond.org:lilypond/media/pictures
 109 rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples
 110 @end verbatim
 111
 112
 113
 114 @subheading Normal maintenance
 115
 116 Get latest source code:
 117
 118 @verbatim
 119 ### update-git.sh
 120 #!/bin/sh
 121 cd $HOME/lilypond/lilypond-git
 122 git fetch origin
 123 git merge origin/master
 124 @end verbatim
 125
 126 Check for any updates to trusted scripts / files:
 127
 128 @verbatim
 129 ### check-git.sh
 130 #!/bin/sh
 131 GIT=$HOME/lilypond/lilypond-git
 132 DEST=$HOME/lilypond/trusted-scripts
 133 diff -u $DEST/website.make $GIT/make/website.make
 134 diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
 135 diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
 136 diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
 137 diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
 138 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
 139 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
 140 diff -u $DEST/bib2texi.py $GIT/scripts/build/bib2texi.py
 141 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
 142 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
 143 @end verbatim
 144
 145 If the changes look ok, make them trusted:
 146
 147 @verbatim
 148 ### copy-from-git.sh
 149 #!/bin/sh
 150 GIT=$HOME/lilypond/lilypond-git
 151 DEST=$HOME/lilypond/trusted-scripts
 152 cp $GIT/make/website.make $DEST/website.make
 153 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
 154 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
 155 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
 156 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
 157 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
 158 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
 159 cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
 160 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
 161 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
 162 @end verbatim
 163
 164 Build the website:
 165
 166 @verbatim
 167 ### make-website.sh
 168 #!/bin/sh
 169 DEST=$HOME/web/
 170 BUILD=$HOME/lilypond/build-website
 171 mkdir -p $BUILD
 172 cd $BUILD
 173 cp $HOME/lilypond/trusted-scripts/website.make .
 174
 175 make -f website.make WEBSITE_ONLY_BUILD=1 website
 176 rsync -raO $BUILD/out-website/website/ $DEST/website/
 177 cp $BUILD/out-website/pictures $DEST
 178 cp $BUILD/out-website/.htaccess $DEST
 179 @end verbatim
 180
 181 Cronjob to automate the trusted portions:
 182
 183 @verbatim
 184 # website-rebuild.cron
 185 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
 186 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
 187 @end verbatim
 188
 189
 190 @subsubheading Additional information
 191
 192 Some information about the website is stored in
 193 @file{~graham/@/lilypond/@/*.txt}; this information should not be
 194 shared with people without trusted access to the server.
 195
 196
 197 @node Debugging website and docs locally
 198 @section Debugging website and docs locally
 199
 200 @itemize
 201 @item
 202 Install apache2, or any other http server.  These instructions
 203 assume that you also enable @code{mod_userdir}, and use
 204 @code{$HOME/public_html} as the location.
 205
 206 @item
 207 Build the online docs and website:
 208
 209 @example
 210 make WEB_TARGETS="offline online" doc
 211 make website
 212 @end example
 213
 214
 215 @item
 216 Move the built stuff into those directories.  It's highly
 217 recommended to have your build dir and www dir on the same
 218 partition.  (make @code{$HOME/public_html/} a symlink if
 219 necessary)
 220
 221 @example
 222 mv out-website/website/ $HOME/public_html
 223 mv $HOME/public_html/website/pictures $HOME/public_html/
 224 mkdir -p $HOME/public_html/doc/v2.13/
 225 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
 226 @end example
 227
 228 @end itemize
 229
 230
 231 @node Translating the website
 232 @section Translating the website
 233
 234 As it has much more audience, the website should be translated before
 235 the documentation; see @ref{Translating the documentation}.
 236
 237 In addition to the normal documentation translation practices,
 238 there are a few additional things to note:
 239
 240 @itemize
 241
 242 @item
 243 Build the website with:
 244
 245 @example
 246 make website
 247 @end example
 248
 249 @noindent
 250 however, please note that this command is not designed for being
 251 run multiple times.  If you see unexpected output (mainly the page
 252 footers getting all messed up), then delete your
 253 @file{out@/-website} directory and run @code{make website} again.
 254
 255 @item
 256 Some of the translation infrastructure is defined in python files;
 257 you must look at the @code{### translation data} sections in:
 258
 259 @example
 260 scripts/build/create-weblinks-itexi.py
 261 scripts/build/website_post.py
 262 @end example
 263
 264 @item
 265 Translations are not included by default in @code{make website}.
 266 To test your translation, edit the @code{WEB_LANGS} line in
 267 @file{make/@/website@/.make}.  Do not submit a patch to add your language
 268 to this file unless @code{make website} completes with less than 5
 269 warnings.
 270
 271 @item
 272 Links to manuals are done with macros like
 273 @code{@@manualDevelLearningSplit}.  To get translated links, you
 274 must change that to @code{@@manualDevelLearningSplit-es} (for
 275 es/Spanish translations, for example).
 276
 277 @end itemize
 278
 279
 280