Mercurial > web-octave
changeset 126:d851f4f89fb4
Improve Makefile deployment mechanism.
* Makefile: Introduce checks for required tools and especially the Jekyll
version. Explain the deployment in detail.
* README.md: Remove verbose section about deployment to the Makefile.
Update documentation. Remove advertising section.
| author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
|---|---|
| date | Fri, 09 Dec 2016 15:18:41 +0100 |
| parents | d79176062baa |
| children | ed065b68cf10 |
| files | Makefile README.md |
| diffstat | 2 files changed, 73 insertions(+), 93 deletions(-) [+] |
line wrap: on
line diff
--- a/Makefile Wed Dec 07 15:22:11 2016 -0800 +++ b/Makefile Fri Dec 09 15:18:41 2016 +0100 @@ -8,15 +8,67 @@ export CVS_RSH -all: deploy +CHECK_GEM := $(shell command -v gem 2> /dev/null) +CHECK_JEKYLL := $(shell command -v jekyll 2> /dev/null) +CHECK_JEKYLL_VERSION = $(shell jekyll --version | grep ^jekyll | sed 's/^.* //g') -deploy: | $(SAVANNAH_DIR) +deploy: | $(SAVANNAH_DIR) check_prerequisites + # + # Build static website into the subdirectory `_site` using Jekyll + # jekyll build + # + # vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv + # DANGAROUS STEP, ommitted by default. + # + # 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, see + # + # https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69 + # + # For some introduction to CVS, see https://savannah.nongnu.org/projects/cvs + # or http://www.cs.umb.edu/~srevilak/cvs.html. + # + # find $(SAVANNAH_DIR) -type f -not -path "*/CVS/*" -exec rm -f '{}' \; + # + # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + # + # Copy the content of that directory `_site` into the checked out + # Savannah CVS (see make target $(SAVANNAH_DIR)). + # cp -a _site/. $(SAVANNAH_DIR) + # + # Add all potential new directories to CVS + # cd $(SAVANNAH_DIR) && find . -type d -not -name "CVS" -exec cvs add '{}' \; + # + # Add all potential new files to CVS (the following command taken from + # http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively + # proved to be fast) + # cd $(SAVANNAH_DIR) && find . -type f | grep -v CVS | xargs cvs add + # + # Commit the chages to get online. + # cd $(SAVANNAH_DIR) && cvs commit + # + # Now everything should be visible to the world. + # + +check_prerequisites: +ifndef CHECK_GEM + $(error "Command `gem` is not available please install rubygems") +endif +ifndef CHECK_JEKYLL + $(error "Command `jekyll` is not available. ${CHECK_JEKYLL_VERSION} Try `gem install jekyll`") +endif +ifneq "3.3" "$(word 1, $(sort 3.3 $(CHECK_JEKYLL_VERSION)))" + $(error "Detected Jekyll version ${CHECK_JEKYLL_VERSION} (>= 3.3 required).") +endif + @echo "All prerequisites fulfilled." $(SAVANNAH_DIR): cd .. \ && cvs -z3 -d:ext:$(USRNAME)@cvs.savannah.gnu.org:/web/octave checkout -P octave + +.DEFAULT_GOAL :=
--- a/README.md Wed Dec 07 15:22:11 2016 -0800 +++ b/README.md Fri Dec 09 15:18:41 2016 +0100 @@ -20,37 +20,6 @@ ## Development -### What makes this way of development better, than the prior? - -- **Official RSS feeds** are **easily** maintained now **at a single place**: - the `_posts` subdirectory, later accessible via - `https://www.gnu.org/software/octave/feed.xml` and automatically spread - to an arbitrary amount of readers, including almost all below mentioned. - - The Octave News are currently very widespread - (and **individually maintained!**) at: - - https://www.gnu.org/software/octave/ (excerpt for the start page) - - https://www.gnu.org/software/octave/news.html (some archive) - - https://www.gnu.org/software/octave/community-news.html (excerpt for the - Octave GUI) - - https://www.gnu.org/software/octave/fixes-4.0.x.html (here are many more - to come!) - - http://wiki.octave.org/GNU_Octave_Wiki#News (some excerpt, anyone can edit) - -- **Content is content**: Page content is primary written in [Markdown][5], - a lightweight Markup language, thus no nasty forgotten HTML tags, that - make content look ugly for any author of a HTML page. - [Jekyll][6] makes valid HTML from [Markdown][5] content. - -- **Easy maintenance**: Just a single command (see below), and [Jekyll][6] - builds a consistent, up-to-date static page. The only maintenance burden, - as it is today anyway: The [Savannah CVS][3] repository. - -[5]: https://daringfireball.net/projects/markdown/syntax -[6]: https://jekyllrb.com/ - - - ### Getting the sources Anyone is free to clone this development repository, simply type @@ -75,16 +44,21 @@ gem install jekyll pygments.rb +A small prerequisite check is performed, by Typing + + make check_prerequisites + For the responsive webpages, we internally use the [Foundation 5][8] framework. All necessary files are already included inside the [hg development repository][2]. +[6]: https://jekyllrb.com/ [7]: https://rubygems.org/ [8]: http://foundation.zurb.com/sites/docs/v/5.5.3/ -### Building the static website +### Building the static website locally All relevant information for Jekyll to build the static website is located in the file `_config.yml`. @@ -112,71 +86,25 @@ -### Typical development tasks +### Add a new RSS post -- **Add a new RSS post** +Duplicate another post in the subdirectory `_posts` and adjust the filename, +especially the date. - Duplicate another post in the subdirectory `_posts` and - adjust the filename, especially the date. +**Be sure to choose the correct categories!!** - **Be sure to choose the correct categories!!** - - `categories: news` is reserved for release announcements, that are also - displayed inside the GUI. Consider choosing another category like - `categories: other` or alike for less important news. +`categories: news` is reserved for release announcements, that are also +displayed inside the GUI. Consider choosing another category like +`categories: other` or alike for less important news. -## Deploying - -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. - -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 checkout -P octave +### Deploying the static website online -Now the following steps are required for deployment -(see [here][9] and [here][10] for some introduction to CVS): - -1. **DO THIS CAREFULLY!!!** If unsure, start with 2. - - 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][11]. - - find <DIR> -type f -not -path "*/CVS/*" -exec rm -f '{}' \; - -2. Now copy the new content of [web-octave][2] subdirectory `_site` into the - [Savannah CVS][3] repository. +For this step you need to have writing permissions to the [Savannah CVS][3] +repository. Usually, it should suffice to type -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 '{}' \; + make deploy - 3. Add all potential new files to CVS (the [following command][12] - 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. - -[9]: https://savannah.nongnu.org/projects/cvs -[10]: http://www.cs.umb.edu/~srevilak/cvs.html -[11]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69 -[12]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively +if anything doesn't work as expected, look at the provided `Makefile` and +perform the steps on your own manually, if necessary.