Build: fix website (1892)

[lilypond.git] / Documentation / contributor / website-work.itexi

diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi
index bb8c19fe949fc7d4bc8c4e529eea521b5c553105..5842493d8d06ecf0f41f947096fc2fc7f4469331 100644 (file)
--- a/Documentation/contributor/website-work.itexi
+++ b/Documentation/contributor/website-work.itexi
@@ -58,6 +58,87 @@ existing website texinfo files.
 @node Uploading and security
 @section Uploading and security
 
+@subheading Building the website from scratch for local checking
+
+Initial setup:
+
+Create directories:
+
+@example
+$HOME/lilypond/
+$HOME/lilypond/media/
+$HOME/lilypond/trusted-scripts/
+@end example
+
+To reduce the CPU burden on the shared host (as well as some
+security concerns), the 'Documentation/pictures/' and
+'Documentation/web/ly-examples/' directories are **not** compiled.
+We will do this ourselves right now.
+
+Go to your lilypond build directory.  make doc.
+
+Set up some variables (you'll only do this once:)
+
+@example
+BUILD_DIR=$HOME/lilypond-git
+PICS=$BUILD_DIR/Documentation/pictures/
+EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/
+@end example
+
+Copy files over:
+
+@example
+cp -r $PICS $HOME/lilypond/media/pictures
+cp -r $EXAMPLES $HOME/lilypond/media/ly-examples
+@end example
+
+Get the scripts you need.  First define these variables:
+
+@example
+GIT=$HOME/lilypond-git
+DEST=$HOME/lilypond/trusted-scripts
+@end example
+
+Then do the copying:
+
+@smallexample
+cp $GIT/make/website.make $DEST/website.make
+cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
+cp $GIT/scripts/build/extract_texi_filenames.py  $DEST/extract_texi_filenames.py
+cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
+cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
+cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
+cp $GIT/scripts/build/website_post.py $DEST/website_post.py
+cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
+cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
+cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
+@end smallexample
+
+Delete your build directory (or maybe just rename your build
+directory to build-old).
+
+@example
+cd $HOME/lilypond
+@end example
+
+Run
+
+@example
+make -f ../lilypond-git/make/website.make WEBSITE_ONLY_BUILD=1 \
+  TOP_SRC_DIR=$HOME/lilypond-git/ \
+  PYTHONPATH=$HOME/lilypond-git/python \
+  TEXI2HTML_PROGRAM=texi2html \
+  website
+@end example
+
+The website should be at:
+
+@example
+$HOME/lilypond/out-website/website/index.html
+@end example
+
+@subheading Building the online website
+
 The website is generated hourly by user @code{graham} the host
 @code{lilypond.org}.  For security reasons, we do not use the
 makefiles and scripts directly from git; copies of the relevant
@@ -124,7 +205,7 @@ git merge origin/master
 @end verbatim
 
 Check for any updates to trusted scripts / files:
-
+@smallexample
 @verbatim
 ### check-git.sh
 #!/bin/sh
@@ -138,6 +219,7 @@ diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.
 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
 diff -u $DEST/bib2texi.py $GIT/scripts/build/bib2texi.py
+diff -u $DEST/langdefs.py $GIT/python/langdefs.py
 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
 @end verbatim
@@ -157,9 +239,11 @@ cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
 cp $GIT/scripts/build/bib2texi.py $DEST/bib2texi.py
+cp $GIT/python/langdefs.py $DEST/langdefs.py
 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
 @end verbatim
+@end smallexample
 
 Build the website:
 
@@ -211,6 +295,10 @@ make WEB_TARGETS="offline online" doc
 make website
 @end example
 
+This will make all the language variants of the website.  To save
+a little time, just the English version can be made with the
+command @code{make WEB_LANGS='' website} or the English and (for
+example) the French with @code{make WEB_LANGS='fr' website}.
 
 @item
 Move the built stuff into those directories.  It's highly
@@ -263,10 +351,12 @@ scripts/build/website_post.py
 
 @item
 Translations are not included by default in @code{make website}.
-To test your translation, edit the @code{WEB_LANGS} line in
-@file{make/website.make}.  Do not submit a patch to add your language
-to this file unless @code{make website} completes with less than 5
-warnings.
+To test your translation, edit the @code{WEB_LANGUAGES =} line in
+@file{python/langdefs.py}.  You will need to copy this updated
+script to @code{build/python/out}.
+
+Do not submit a patch to add your language to this file unless
+@code{make website} completes with fewer than 5 warnings.
 
 @item
 Links to manuals are done with macros like