# HG changeset patch # User Kai T. Ohlhus # Date 1476722054 -7200 # Node ID bc79072a816960aa25251051b7b754ae9e6a85e2 # Parent b748a89a04b0536a960ba3674de6974ea856015e Update README with suggestion for future deployment. diff -r b748a89a04b0 -r bc79072a8169 README.md --- a/README.md Fri Oct 14 03:15:33 2016 +0200 +++ b/README.md Mon Oct 17 18:34:14 2016 +0200 @@ -1,36 +1,128 @@ # octave-web -Proposed update of [octave.org](http://www.octave.org). + +This is the [http://www.octave.org][1] website development repository. + +The development and deployment workflow in short: -## Developing - -- Install Jekyll from Rubygems - - `gem install jekyll` +1. The website is developed in this [web-octave][2] Mercurial repository. +2. Static HTML pages are generated from this [web-octave][2] repository + and are deployed at the [Savannah CVS][3] repository. +3. After deploying the static pages, they are visible from + [http://www.octave.org][1], that redirects to + [https://www.gnu.org/software/octave][4]. -- Compile the assets into `_site` (this directory is ignored by revision control and will be created on first build) +[1]: http://www.octave.org +[2]: http://hg.octave.org/web-octave +[3]: http://web.cvs.savannah.gnu.org/viewvc/octave/?root=octave +[4]: https://www.gnu.org/software/octave - `jekyll build` + + +## Development + +### Getting the sources -- Serve the site +Anyone is free to clone this development repository, simply type + + hg clone http://hg.octave.org/web-octave - `jekyll serve --watch` +to get anonymous read access without writing privileges. +To push your changes, please contact the octave developers at +`maintainers@octave.org`. -### Website HG repository +If you already have writing permissions for this repository, +you should clone the repository using hg clone ssh://gnuoctave@octave.org/hg/web-octave -## Configuring -See [_config.yml](_config.yml). In particular, `baseurl` will need to be adjusted to match the path of the subdirectory where the site will be hosted, e.g., for `gnu.org/octave` use `/octave`. Currently `baseurl` is set to the repository name in order to work with the Github Pages' build service. + + +### Building requisites + +To build the static website, you need to install [Jekyll][5] and a few more +tools from [Rubygems][6]. Just type + + gem install jekyll jekyll-octicons pygments.rb + +[5]: https://jekyllrb.com/ +[6]: https://rubygems.org/ + + + +### Building the static website + +All relevant information for Jekyll to build the static website is located +in the file `_config.yml`. +Typing + + jekyll build + +from the repositories root directory will build a complete static website +into the subdirectory `_site` using this information (this directory is +ignored by Mercurial and will be created on first build). + +Especially for development, it is beneficial to watch the changes locally +before pushing any changes. +Jekyll provides a local webserver by typing + + jekyll serve + +and rebuilds the whole static website automatically, as it monitors any +file changes. + + ## Deploying -- Configure paths as needed in `_config.yml` -- Build the static site - `jekyll build` +After building the static website from [web-octave][2] into the +the subdirectory `_site` using Jekyll it can be deployed at the +[Savannah CVS][3] repository to become visible to the world. -- Copy the static assets from `_site` to a server. - -### Website CVS repository at Savannah +Therefore, checkout the [Savannah CVS][3] repository somewhere +outside the [web-octave][2] directory, typing export CVS_RSH=ssh - cvs -z3 -d:ext:@cvs.savannah.gnu.org:/web/octave co octave + cvs -z3 -d:ext:@cvs.savannah.gnu.org:/web/octave checkout -P octave + +Now the following steps are required for deployment +(see [here][7] and [here][8] for some introduction to CVS): + +1. Remove all previous files in the target directory, + *but no directories at all or CVS related stuff*! + This is due to a [limitation of CVS][9]. + + find octave -type f -not -path "*/CVS/*" -exec rm -f '{}' \; + + *Note:* `octave` in the command above is the name of the checked out + [Savannah CVS][3] repository. + +2. Now copy the new content of [web-octave][2] subdirectory `_site` into the + [Savannah CVS][3] repository. + +3. Then in the [Savannah CVS][3] repository: + + cd octave + + 1. Remove all no longer existent files + + cvs remove + + 2. Add all potential new directories to CVS + + find . -type d -not -name "CVS" -exec cvs add '{}' \; + + 3. Add all potential new files to CVS (the [following command][10] + proved to me fast) + + find . -type f | grep -v CVS | xargs cvs add + + 4. Commit the chages to get online + + cvs commit + +Now everything should be visible to the world. + +[7]: https://savannah.nongnu.org/projects/cvs +[8]: http://www.cs.umb.edu/~srevilak/cvs.html +[9]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69 +[10]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively diff -r b748a89a04b0 -r bc79072a8169 _config.yml --- a/_config.yml Fri Oct 14 03:15:33 2016 +0200 +++ b/_config.yml Mon Oct 17 18:34:14 2016 +0200 @@ -10,11 +10,12 @@ email: maintainers@octave.org description: > # this means to ignore newlines until "baseurl:" GNU Octave is a programming language for scientific computing. -baseurl: "/octave-web" # the subpath of your site, e.g. /blog -url: "//www.gnu.org" # the base hostname & protocol for your site -wiki_url: "//wiki.octave.org" -faq_url: "//wiki.octave.org/faq" -docs_url: "//www.gnu.org/software/octave/doc/interpreter" +baseurl: "/software/octave" # the subpath of your site, e.g. /blog +url: "https://www.gnu.org" # the base hostname & protocol for your site +wiki_url: "http://wiki.octave.org" +faq_url: "http://wiki.octave.org/faq" +docs_url: "https://www.gnu.org/software/octave/doc/interpreter" +bugs_url: "https://savannah.gnu.org/bugs/?group=octave" maintainers_email: "maintainers@octave.org" help_email: "help@octave.org" irc_channel: "#octave" diff -r b748a89a04b0 -r bc79072a8169 _config_octave.yml --- a/_config_octave.yml Fri Oct 14 03:15:33 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ -# Site settings for deployment under https://www.gnu.org/software/octave -# build with -# -# > jekyll build --config _config.yml,_config_octave.yml -# -baseurl: "/software/octave/new" # the subpath of your site, e.g. /blog diff -r b748a89a04b0 -r bc79072a8169 _config_test.yml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/_config_test.yml Mon Oct 17 18:34:14 2016 +0200 @@ -0,0 +1,9 @@ +# Site settings for deployment under a test URL +# +# https://www.gnu.org/software/octave/new +# +# Build with +# +# jekyll build --config _config.yml,_config_test.yml +# +baseurl: "/software/octave/new" # the subpath of your site, e.g. /blog