X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fwebsite-work.itexi;h=5842493d8d06ecf0f41f947096fc2fc7f4469331;hb=463be0c9f1784d5755459e87fe0929e5ad293eb7;hp=c1a6815e9058f0c9e8e77d858a54f530ec951327;hpb=5351678f4821374c9cbaf55b92cd35436d786c1d;p=lilypond.git diff --git a/Documentation/contributor/website-work.itexi b/Documentation/contributor/website-work.itexi index c1a6815e90..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 @@ -16,10 +17,10 @@ The website is @emph{not} written directly in HTML; instead, the source is Texinfo, which is then generated into HTML, PDF, and Info formats. The sources are -@verbatim +@example Documentation/web.texi Documentation/web/*.texi -@end verbatim +@end example Unless otherwise specified, follow the instructions and policies given in @ref{Documentation work}. That chapter also contains a @@ -39,11 +40,17 @@ 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 For anything not listed here, just follow the same style as the -existing texinfo files. +existing website texinfo files. @end itemize @@ -51,6 +58,87 @@ existing 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 @@ -77,6 +165,32 @@ chgrp lilypond ~graham/lilypond/ -R 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 +@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/lilypond/media} on the host. + +Upload latest pictures/ and ly-examples/ (local script): + +@warning{You may need to change a number of items in the below +script.} + +@verbatim +### upload-lily-web-media.sh +#!/bin/sh +BUILD_DIR=$HOME/src/build-lilypond + +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:lilypond/media/pictures +rsync -a $EXAMPLES graham@lilypond.org:lilypond/media/ly-examples +@end verbatim + + @subheading Normal maintenance @@ -91,7 +205,7 @@ git merge origin/master @end verbatim Check for any updates to trusted scripts / files: - +@smallexample @verbatim ### check-git.sh #!/bin/sh @@ -104,6 +218,8 @@ diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py 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 @@ -122,9 +238,12 @@ 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/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: @@ -152,34 +271,49 @@ Cronjob to automate the trusted portions: @end verbatim -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 @strong{not} -compiled. If you modify any files in those directories, a user in -the @code{lilypond} group must upload them to @file{~graham/media} -on the host. +@subsubheading Additional information -Upload latest pictures/ and ly-examples/ (local script): +Some information about the website is stored in +@file{~graham/lilypond/*.txt}; this information should not be +shared with people without trusted access to the server. -@verbatim -### upload-lily-web-media.sh -#!/bin/sh -BUILD_DIR=$HOME/src/build-lilypond -PICS=$BUILD_DIR/Documentation/pictures/out-www/ -EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/ +@node Debugging website and docs locally +@section Debugging website and docs locally -cd $BUILD_DIR -rsync -a $PICS graham@lilypond.org:media/pictures -rsync -a $EXAMPLES graham@lilypond.org:ly-examples -@end verbatim +@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: -@subsubheading Additional information +@example +make WEB_TARGETS="offline online" doc +make website +@end example -Some information about the website is stored in -@file{~graham/lilypond/*.txt}; this information should not be -shared with people without trusted access to the server. +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 @@ -217,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