X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fwebsite-work.itexi;h=5842493d8d06ecf0f41f947096fc2fc7f4469331;hb=463be0c9f1784d5755459e87fe0929e5ad293eb7;hp=4d71c32e97e2400b18f00b751c7797f186517889;hpb=da37729bfb10265dfc170bc2416b426b55476fb0;p=lilypond.git diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi index 4d71c32e97..5842493d8d 100644 --- a/Documentation/contributor/website-work.itexi +++ b/Documentation/contributor/website-work.itexi @@ -3,8 +3,9 @@ @chapter Website work @menu -* Introduction to website work:: +* Introduction to website work:: * Uploading and security:: +* Debugging website and docs locally:: * Translating the website:: @end menu @@ -39,6 +40,12 @@ subsections or subsubsections. link to any pieces of automatically generated documentation, like the IR or certain NR appendices. +@item +The bibliography in Community->Publications is generated automatically +from @file{.bib} files; formatting is done automatically by +@file{texi-web.bst}. + +@item @dots{} @item @@ -51,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 @@ -60,16 +148,16 @@ scripts are examined and copied to @subheading Initial setup You should symlink your own @file{~/lilypond/} to -@file{~graham/@/lilypond/} +@file{~graham/lilypond/} If this directory does not exist, make it. Git master should go -in @file{~/lilypond/@/lilypond@/-git/} but make sure you enable: +in @file{~/lilypond/lilypond-git/} but make sure you enable: @example git config core.filemode false @end example -If you have created any files in @file{~graham/@/lilypond/} then +If you have created any files in @file{~graham/lilypond/} then please run: @example @@ -78,11 +166,11 @@ chmod 775 ~graham/lilypond/ -R @end example To reduce the CPU burden on the shared host (as well as some -security concerns), the @file{Documentation/@/pictures/} and -@file{Documentation/@/web/@/ly-examples/} directories are +security concerns), the @file{Documentation/pictures/} and +@file{Documentation/web/ly-examples/} directories are @strong{not} compiled. You need to upload them, and if they ever change, a user in the @code{lilypond} group must upload them to -@file{~graham/@/media} on the host. +@file{~graham/lilypond/media} on the host. Upload latest pictures/ and ly-examples/ (local script): @@ -98,8 +186,8 @@ PICS=$BUILD_DIR/Documentation/pictures/out-www/ EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/ cd $BUILD_DIR -rsync -a $PICS graham@lilypond.org:media/pictures -rsync -a $EXAMPLES graham@lilypond.org:ly-examples +rsync -a $PICS graham@lilypond.org:lilypond/media/pictures +rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples @end verbatim @@ -117,7 +205,7 @@ git merge origin/master @end verbatim Check for any updates to trusted scripts / files: - +@smallexample @verbatim ### check-git.sh #!/bin/sh @@ -131,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 @@ -150,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: @@ -183,10 +274,48 @@ Cronjob to automate the trusted portions: @subsubheading Additional information Some information about the website is stored in -@file{~graham/@/lilypond/@/*.txt}; this information should not be +@file{~graham/lilypond/*.txt}; this information should not be shared with people without trusted access to the server. +@node Debugging website and docs locally +@section Debugging website and docs locally + +@itemize +@item +Install apache2, or any other http server. These instructions +assume that you also enable @code{mod_userdir}, and use +@code{$HOME/public_html} as the location. + +@item +Build the online docs and website: + +@example +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 +recommended to have your build dir and www dir on the same +partition. (make @code{$HOME/public_html/} a symlink if +necessary) + +@example +mv out-website/website/ $HOME/public_html +mv $HOME/public_html/website/pictures $HOME/public_html/ +mkdir -p $HOME/public_html/doc/v2.13/ +mv out-www/online-root/* $HOME/public_html/doc/v2.13/ +@end example + +@end itemize + + @node Translating the website @section Translating the website @@ -209,7 +338,7 @@ make website however, please note that this command is not designed for being run multiple times. If you see unexpected output (mainly the page footers getting all messed up), then delete your -@file{out@/-website} directory and run @code{make website} again. +@file{out-website} directory and run @code{make website} again. @item Some of the translation infrastructure is defined in python files; @@ -222,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