Mercurial > web-octave

comparison README.md @ 94:e8fc61e077fc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged closed branch "kai" into default.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Tue, 01 Nov 2016 01:06:10 +0100
parents beb4387a8937
children e7efa40deb17
comparison
equal deleted inserted replaced
92:7609e2a6faef 94:e8fc61e077fc
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 - Install Jekyll from Rubygems
6
7 `gem install jekyll`
8
9 - Compile the assets into `_site` (this directory is ignored by revision control and will be created on first build)
10
11 `jekyll build`
12
13 - Serve the site
14 4
15 `jekyll serve --watch` 5 The development and deployment workflow in short:
16 6
17 ## Configuring 7 1. The website is developed in this [web-octave][2] Mercurial repository.
18 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. 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].
13
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
18
19
20
21 ## Development
22
23 ### What makes this way of development better, than the prior?
24
25 - **Official RSS feeds** are **easily** maintained now **at a single place**:
26 the `_posts` subdirectory, later accessible via
27 `https://www.gnu.org/software/octave/feed.xml` and automatically spread
28 to an arbitrary amount of readers, including almost all below mentioned.
29
30 The Octave News are currently very widespread
31 (and **individually maintained!**) at:
32 - https://www.gnu.org/software/octave/ (excerpt for the start page)
33 - https://www.gnu.org/software/octave/news.html (some archive)
34 - https://www.gnu.org/software/octave/community-news.html (excerpt for the
35 Octave GUI)
36 - https://www.gnu.org/software/octave/fixes-4.0.x.html (here are many more
37 to come!)
38 - http://wiki.octave.org/GNU_Octave_Wiki#News (some excerpt, anyone can edit)
39
40 - **Content is content**: Page content is primary written in [Markdown][5],
41 a lightweight Markup language, thus no nasty forgotten HTML tags, that
42 make content look ugly for any author of a HTML page.
43 [Jekyll][6] makes valid HTML from [Markdown][5] content.
44
45 - **Easy maintenance**: Just a single command (see below), and [Jekyll][6]
46 builds a consistent, up-to-date static page. The only maintenance burden,
47 as it is today anyway: The [Savannah CVS][3] repository.
48
49 [5]: https://daringfireball.net/projects/markdown/syntax
50 [6]: https://jekyllrb.com/
51
52
53
54 ### Getting the sources
55
56 Anyone is free to clone this development repository, simply type
57
58 hg clone http://hg.octave.org/web-octave
59
60 to get anonymous read access without writing privileges.
61 To push your changes, please contact the octave developers at
62 `maintainers@octave.org`.
63
64 If you already have writing permissions for this repository,
65 you should clone the repository using
66
67 hg clone ssh://gnuoctave@octave.org/hg/web-octave
68
69
70
71 ### Building requisites
72
73 To build the static website, you need to install [Jekyll][6] and a few more
74 tools from [Rubygems][7]. Just type
75
76 gem install jekyll jekyll-octicons pygments.rb
77
78 [7]: https://rubygems.org/
79
80
81
82 ### Building the static website
83
84 All relevant information for Jekyll to build the static website is located
85 in the file `_config.yml`.
86 Typing
87
88 jekyll build
89
90 from the repositories root directory will build a complete static website
91 into the subdirectory `_site` using this information (this directory is
92 ignored by Mercurial and will be created on first build).
93
94 Especially for development, it is beneficial to watch the changes locally
95 before pushing any changes.
96 Jekyll provides a local webserver by typing
97
98 jekyll serve
99
100 and rebuilds the whole static website automatically, as it monitors any
101 file changes.
102
103 To build the test page, that can be deployed at some subdirectory, e.g.
104 `http://www.octave.org/new`, use
105
106 jekyll build --config _config.yml,_config_test.yml
107
108
109
110 ### Typical development tasks
111
112 - **Add a new RSS post**
113
114 Duplicate another post in the subdirectory `_posts` and
115 adjust the filename, especially the date
116
117
118
119
19 120
20 ## Deploying 121 ## Deploying
21 - Configure paths as needed in `_config.yml`
22 - Build the static site
23
24 `jekyll build`
25 122
26 - Copy the static assets from `_site` to a server. 123 After building the static website from [web-octave][2] into the
124 the subdirectory `_site` using Jekyll it can be deployed at the
125 [Savannah CVS][3] repository to become visible to the world.
126
127 Therefore, checkout the [Savannah CVS][3] repository somewhere
128 outside the [web-octave][2] directory, typing
129
130 export CVS_RSH=ssh
131 cvs -z3 -d:ext:<Savannah account>@cvs.savannah.gnu.org:/web/octave checkout -P octave
132
133 Now the following steps are required for deployment
134 (see [here][8] and [here][9] for some introduction to CVS):
135
136 1. Remove all previous files in the target directory,
137 *but no directories at all or CVS related stuff*!
138 This is due to a [limitation of CVS][10].
139
140 find octave -type f -not -path "*/CVS/*" -exec rm -f '{}' \;
141
142 *Note:* `octave` in the command above is the name of the checked out
143 [Savannah CVS][3] repository.
144
145 2. Now copy the new content of [web-octave][2] subdirectory `_site` into the
146 [Savannah CVS][3] repository.
147
148 3. Then in the [Savannah CVS][3] repository:
149
150 cd octave
151
152 1. Remove all no longer existent files
153
154 cvs remove
155
156 2. Add all potential new directories to CVS
157
158 find . -type d -not -name "CVS" -exec cvs add '{}' \;
159
160 3. Add all potential new files to CVS (the [following command][11]
161 proved to me fast)
162
163 find . -type f | grep -v CVS | xargs cvs add
164
165 4. Commit the chages to get online
166
167 cvs commit
168
169 Now everything should be visible to the world.
170
171 [8]: https://savannah.nongnu.org/projects/cvs
172 [9]: http://www.cs.umb.edu/~srevilak/cvs.html
173 [10]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69
174 [11]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively