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 apache2, or any other http server.  These instructions
 295 assume that you also enable @code{mod_userdir}, and use
 296 @code{$HOME/public_html/lilypond.org} as the location.
 297
 298 @item
 299 Build the online docs and website:
 300
 301 @example
 302 make WEB_TARGETS="offline online" doc
 303 make website
 304 @end example
 305
 306 This will make all the language variants of the website.  To save
 307 a little time, just the English version can be made with the
 308 command @code{make WEB_LANGS='' website} or the English and (for
 309 example) the French with @code{make WEB_LANGS='fr' website}.
 310
 311 @item
 312 Move the built stuff into those directories.  It's highly
 313 recommended to have your build dir and www dir on the same
 314 partition.  (make @code{$HOME/public_html/lilypond.org} a symlink
 315 if necessary)
 316
 317 @example
 318 mv out-website/website $HOME/public_html/lilypond.org/
 319 mkdir -p $HOME/public_html/lilypond.org/doc/v2.19/
 320 mv out-www/online-root/* $HOME/public_html/lilypond.org/doc/v2.19/
 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{$LILYPOND_BUILD_DIR/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