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