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 @subheading Overall idea
  62
  63 To reduce the CPU burden on the shared host (as well as some
  64 security concerns), we do not compile all of LilyPond.  The
  65 website build process runs @code{texi2html}, but all media files
  66 (be they graphical @code{lilypond} output, photos of people, or
  67 pdfs) are copied from the @code{$LILYPOND_WEB_MEDIA_GIT}
  68 repository.
  69
  70 All scripts and makefiles used for the website build are run from
  71 a @qq{trusted} copy.  Any modification to those files in git needs
  72 a human to review the changes (after they have been made in git)
  73 before they are used on the server.
  74
  75
  76 @subheading Building the website (quick local)
  77
  78 Initial setup: make sure that you have the environment variables
  79 @code{$LILYPOND_GIT} and @code{$LILYPOND_WEB_MEDIA_GIT} set up
  80 correctly.  For more information, see @ref{Other repositories}.
  81
  82 Once that is done,
  83
  84 @example
  85 cd $LILYPOND_GIT/build/
  86 make website
  87 @end example
  88
  89 The website is in @file{out-website/website/index.html}.
  90
  91
  92 @subheading Building the website (exactly as on the server)
  93
  94 @subsubheading Setting up (exactly as on the server)
  95
  96 Initial setup: you still need @code{$LILYPOND_GIT} and
  97 @code{$LILYPOND_WEB_MEDIA_GIT}.
  98
  99 Once that's done, create:
 100
 101 @example
 102 mkdir -p $HOME/lilypond/
 103 mkdir -p $HOME/lilypond/bin/
 104 mkdir -p $HOME/lilypond/cron/
 105 mkdir -p $HOME/lilypond/trusted-scripts/
 106 @end example
 107
 108 The add these files to @file{$HOME/lilypond/bin/}:
 109
 110 Update git repositories:
 111
 112 @smallexample
 113 @verbatim
 114 ### update-git.sh
 115 #!/bin/sh
 116 cd $LILYPOND_GIT
 117 git fetch origin
 118 git merge origin/master
 119 cd $LILYPOND_WEB_MEDIA_GIT
 120 git fetch origin
 121 git merge origin/master
 122 @end verbatim
 123 @end smallexample
 124
 125 Check for any updates to trusted scripts / files:
 126
 127 @smallexample
 128 @verbatim
 129 ### check-git.sh
 130 #!/bin/sh
 131 DEST=$HOME/lilypond/trusted-scripts
 132 diff -u $DEST/website.make \
 133   $LILYPOND_GIT/make/website.make
 134 diff -u $DEST/lilypond-texi2html.init \
 135   $LILYPOND_GIT/Documentation/lilypond-texi2html.init
 136 diff -u $DEST/extract_texi_filenames.py \
 137   $LILYPOND_GIT/scripts/build/extract_texi_filenames.py
 138 diff -u $DEST/create-version-itexi.py \
 139   $LILYPOND_GIT/scripts/build/create-version-itexi.py
 140 diff -u $DEST/create-weblinks-itexi.py \
 141   $LILYPOND_GIT/scripts/build/create-weblinks-itexi.py
 142 diff -u $DEST/mass-link.py \
 143   $LILYPOND_GIT/scripts/build/mass-link.py
 144 diff -u $DEST/website_post.py \
 145   $LILYPOND_GIT/scripts/build/website_post.py
 146 diff -u $DEST/bib2texi.py \
 147   $LILYPOND_GIT/scripts/build/bib2texi.py
 148 diff -u $DEST/langdefs.py \
 149   $LILYPOND_GIT/python/langdefs.py
 150 diff -u $DEST/lilypond.org.htaccess \
 151   $LILYPOND_GIT/Documentation/web/server/lilypond.org.htaccess
 152 diff -u $DEST/website-dir.htaccess \
 153   $LILYPOND_GIT/Documentation/web/server/website-dir.htaccess
 154 @end verbatim
 155 @end smallexample
 156
 157 If the changes look ok, make them trusted:
 158
 159 @smallexample
 160 @verbatim
 161 ### copy-from-git.sh
 162 #!/bin/sh
 163 DEST=$HOME/lilypond/trusted-scripts
 164 cp $LILYPOND_GIT/make/website.make \
 165   $DEST/website.make
 166 cp $LILYPOND_GIT/Documentation/lilypond-texi2html.init \
 167   $DEST/lilypond-texi2html.init
 168 cp $LILYPOND_GIT/scripts/build/extract_texi_filenames.py \
 169   $DEST/extract_texi_filenames.py
 170 cp $LILYPOND_GIT/scripts/build/create-version-itexi.py \
 171   $DEST/create-version-itexi.py
 172 cp $LILYPOND_GIT/scripts/build/create-weblinks-itexi.py \
 173   $DEST/create-weblinks-itexi.py
 174 cp $LILYPOND_GIT/scripts/build/mass-link.py \
 175   $DEST/mass-link.py
 176 cp $LILYPOND_GIT/scripts/build/website_post.py \
 177   $DEST/website_post.py
 178 cp $LILYPOND_GIT/scripts/build/bib2texi.py \
 179   $DEST/bib2texi.py
 180 cp $LILYPOND_GIT/python/langdefs.py \
 181   $DEST/langdefs.py
 182 cp $LILYPOND_GIT/Documentation/web/server/lilypond.org.htaccess \
 183   $DEST/lilypond.org.htaccess
 184 cp $LILYPOND_GIT/Documentation/web/server/website-dir.htaccess \
 185   $DEST/website-dir.htaccess
 186 @end verbatim
 187 @end smallexample
 188
 189 Build the website:
 190
 191 @smallexample
 192 @verbatim
 193 ### make-website.sh
 194 #!/bin/sh
 195 DEST=$HOME/web/
 196 BUILD=$HOME/lilypond/build-website
 197 mkdir -p $BUILD
 198 cd $BUILD
 199 cp $HOME/lilypond/trusted-scripts/website.make .
 200
 201 make -f website.make WEBSITE_ONLY_BUILD=1 website
 202 rsync -raO $BUILD/out-website/website/ $DEST/website/
 203 cp $BUILD/out-website/pictures $DEST
 204 cp $BUILD/out-website/.htaccess $DEST
 205 @end verbatim
 206 @end smallexample
 207
 208 Then in the @file{cronjob/} directory, put the cronjob to automate
 209 the trusted portions:
 210
 211 @warning{@code{cron} will not inherit environment variables from
 212 your main setup, so you must re-define any variables inside your
 213 @code{crontab}.}
 214
 215 @smallexample
 216 @verbatim
 217 # website-rebuild.cron
 218 LILYPOND_GIT=   ... fill this in
 219 LILYPOND_WEB_MEDIA_GIT=   ... fill this in
 220
 221 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
 222 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
 223 @end verbatim
 224 @end smallexample
 225
 226 As the final stage of the setup, run your @code{copy-from-git.sh}
 227 script, assuming that you trust the current state of scripts in
 228 lilypond git.
 229
 230 @subsubheading Normal maintenance
 231
 232 When there is a change to the build scripts and/or website
 233 makefile, log in to the server (or your own home machine if you're
 234 testing this there), and do
 235
 236 @example
 237 update-git.sh
 238 check-git.sh
 239 @end example
 240
 241 After reviewing the changes carefully, you can update the trusted
 242 scripts with @code{copy-from-git.sh}.
 243
 244
 245 @subsubheading Building the website (exactly as on the server)
 246
 247 Run @code{make-website.sh}; the final version ends up in
 248 @file{$HOME/web/}.
 249
 250 On the actual server, the website is generated hourly by user
 251 @code{graham} the host @code{lilypond.org}.  You can set up the
 252 cronjob by doing:
 253
 254 @example
 255 crontab $HOME/lilypond/website-rebuild.cron
 256 @end example
 257
 258
 259 @subheading Initial setup for new users on actual serve
 260
 261 You should symlink your own @file{~/lilypond/} to
 262 @file{~graham/lilypond/}
 263
 264 If this directory does not exist, make it.  Git master should go
 265 in @file{~/lilypond/lilypond-git/} but make sure you enable:
 266
 267 @example
 268 git config core.filemode false
 269 @end example
 270
 271 If you have created any files in @file{~graham/lilypond/} then
 272 please run:
 273
 274 @example
 275 chgrp lilypond ~graham/lilypond/ -R
 276 chmod 775 ~graham/lilypond/ -R
 277 @end example
 278
 279
 280
 281 @subsubheading Additional information
 282
 283 Some information about the website is stored in
 284 @file{~graham/lilypond/*.txt}; this information should not be
 285 shared with people without trusted access to the server.
 286
 287
 288 @node Debugging website and docs locally
 289 @section Debugging website and docs locally
 290
 291 @itemize
 292 @item
 293 Install apache2, or any other http server.  These instructions
 294 assume that you also enable @code{mod_userdir}, and use
 295 @code{$HOME/public_html} as the location.
 296
 297 @item
 298 Build the online docs and website:
 299
 300 @example
 301 make WEB_TARGETS="offline online" doc
 302 make website
 303 @end example
 304
 305 This will make all the language variants of the website.  To save
 306 a little time, just the English version can be made with the
 307 command @code{make WEB_LANGS='' website} or the English and (for
 308 example) the French with @code{make WEB_LANGS='fr' website}.
 309
 310 @item
 311 Move the built stuff into those directories.  It's highly
 312 recommended to have your build dir and www dir on the same
 313 partition.  (make @code{$HOME/public_html/} a symlink if
 314 necessary)
 315
 316 @example
 317 mv out-website/website/ $HOME/public_html
 318 mv $HOME/public_html/website/pictures $HOME/public_html/
 319 mkdir -p $HOME/public_html/doc/v2.13/
 320 mv out-www/online-root/* $HOME/public_html/doc/v2.13/
 321 @end example
 322
 323 @end itemize
 324
 325
 326 @node Translating the website
 327 @section Translating the website
 328
 329 As it has much more audience, the website should be translated before
 330 the documentation; see @ref{Translating the documentation}.
 331
 332 In addition to the normal documentation translation practices,
 333 there are a few additional things to note:
 334
 335 @itemize
 336
 337 @item
 338 Build the website with:
 339
 340 @example
 341 make website
 342 @end example
 343
 344 @noindent
 345 however, please note that this command is not designed for being
 346 run multiple times.  If you see unexpected output (mainly the page
 347 footers getting all messed up), then delete your
 348 @file{out-website} directory and run @code{make website} again.
 349
 350 @item
 351 Some of the translation infrastructure is defined in python files;
 352 you must look at the @code{### translation data} sections in:
 353
 354 @example
 355 scripts/build/create-weblinks-itexi.py
 356 scripts/build/website_post.py
 357 @end example
 358
 359 @item
 360 Translations are not included by default in @code{make website}.
 361 To test your translation, edit the @code{WEB_LANGUAGES =} line in
 362 @file{python/langdefs.py}.  You will need to copy this updated
 363 script to @code{build/python/out}.
 364
 365 Do not submit a patch to add your language to this file unless
 366 @code{make website} completes with fewer than 5 warnings.
 367
 368 @item
 369 Links to manuals are done with macros like
 370 @code{@@manualDevelLearningSplit}.  To get translated links, you
 371 must change that to @code{@@manualDevelLearningSplit-es} (for
 372 es/Spanish translations, for example).
 373
 374 @end itemize
 375
 376
 377