Mercurial > web-octave

comparison README.md @ 82:bc79072a8169 kai

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 48f5e0fda5a8
children 3269c95e98d9
comparison
equal deleted inserted replaced
81:b748a89a04b0 82:bc79072a8169
1 # octave-web 1 # octave-web
2 Proposed update of [octave.org](http://www.octave.org).
3 2
4 ## Developing 3 This is the [http://www.octave.org][1] website development repository.
5 4
6 - Install Jekyll from Rubygems 5 The development and deployment workflow in short:
7 6
8 `gem install jekyll` 7 1. The website is developed in this [web-octave][2] Mercurial repository.
8 2. Static HTML pages are generated from this [web-octave][2] repository
9 and are deployed at the [Savannah CVS][3] repository.
10 3. After deploying the static pages, they are visible from
11 [http://www.octave.org][1], that redirects to
12 [https://www.gnu.org/software/octave][4].
9 13
10 - Compile the assets into `_site` (this directory is ignored by revision control and will be created on first build) 14 [1]: http://www.octave.org
15 [2]: http://hg.octave.org/web-octave
16 [3]: http://web.cvs.savannah.gnu.org/viewvc/octave/?root=octave
17 [4]: https://www.gnu.org/software/octave
11 18
12 `jekyll build`
13 19
14 - Serve the site
15 20
16 `jekyll serve --watch` 21 ## Development
17 22
18 ### Website HG repository 23 ### Getting the sources
24
25 Anyone is free to clone this development repository, simply type
26
27 hg clone http://hg.octave.org/web-octave
28
29 to get anonymous read access without writing privileges.
30 To push your changes, please contact the octave developers at
31 `maintainers@octave.org`.
32
33 If you already have writing permissions for this repository,
34 you should clone the repository using
19 35
20 hg clone ssh://gnuoctave@octave.org/hg/web-octave 36 hg clone ssh://gnuoctave@octave.org/hg/web-octave
21 37
22 ## Configuring 38
23 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. 39
40 ### Building requisites
41
42 To build the static website, you need to install [Jekyll][5] and a few more
43 tools from [Rubygems][6]. Just type
44
45 gem install jekyll jekyll-octicons pygments.rb
46
47 [5]: https://jekyllrb.com/
48 [6]: https://rubygems.org/
49
50
51
52 ### Building the static website
53
54 All relevant information for Jekyll to build the static website is located
55 in the file `_config.yml`.
56 Typing
57
58 jekyll build
59
60 from the repositories root directory will build a complete static website
61 into the subdirectory `_site` using this information (this directory is
62 ignored by Mercurial and will be created on first build).
63
64 Especially for development, it is beneficial to watch the changes locally
65 before pushing any changes.
66 Jekyll provides a local webserver by typing
67
68 jekyll serve
69
70 and rebuilds the whole static website automatically, as it monitors any
71 file changes.
72
73
24 74
25 ## Deploying 75 ## Deploying
26 - Configure paths as needed in `_config.yml`
27 - Build the static site
28 76
29 `jekyll build` 77 After building the static website from [web-octave][2] into the
78 the subdirectory `_site` using Jekyll it can be deployed at the
79 [Savannah CVS][3] repository to become visible to the world.
30 80
31 - Copy the static assets from `_site` to a server. 81 Therefore, checkout the [Savannah CVS][3] repository somewhere
32 82 outside the [web-octave][2] directory, typing
33 ### Website CVS repository at Savannah
34 83
35 export CVS_RSH=ssh 84 export CVS_RSH=ssh
36 cvs -z3 -d:ext:<Savannah account>@cvs.savannah.gnu.org:/web/octave co octave 85 cvs -z3 -d:ext:<Savannah account>@cvs.savannah.gnu.org:/web/octave checkout -P octave
86
87 Now the following steps are required for deployment
88 (see [here][7] and [here][8] for some introduction to CVS):
89
90 1. Remove all previous files in the target directory,
91 *but no directories at all or CVS related stuff*!
92 This is due to a [limitation of CVS][9].
93
94 find octave -type f -not -path "*/CVS/*" -exec rm -f '{}' \;
95
96 *Note:* `octave` in the command above is the name of the checked out
97 [Savannah CVS][3] repository.
98
99 2. Now copy the new content of [web-octave][2] subdirectory `_site` into the
100 [Savannah CVS][3] repository.
101
102 3. Then in the [Savannah CVS][3] repository:
103
104 cd octave
105
106 1. Remove all no longer existent files
107
108 cvs remove
109
110 2. Add all potential new directories to CVS
111
112 find . -type d -not -name "CVS" -exec cvs add '{}' \;
113
114 3. Add all potential new files to CVS (the [following command][10]
115 proved to me fast)
116
117 find . -type f | grep -v CVS | xargs cvs add
118
119 4. Commit the chages to get online
120
121 cvs commit
122
123 Now everything should be visible to the world.
124
125 [7]: https://savannah.nongnu.org/projects/cvs
126 [8]: http://www.cs.umb.edu/~srevilak/cvs.html
127 [9]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69
128 [10]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively