changeset 82:bc79072a8169 kai

Update README with suggestion for future deployment.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Mon, 17 Oct 2016 18:34:14 +0200
parents b748a89a04b0
children ed7a53f68316
files README.md _config.yml _config_octave.yml _config_test.yml
diffstat 4 files changed, 127 insertions(+), 31 deletions(-) [+]
line wrap: on
line diff
--- 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:<Savannah account>@cvs.savannah.gnu.org:/web/octave co octave
+    cvs -z3 -d:ext:<Savannah account>@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
--- 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"
--- 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
--- /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