Mercurial > web-octave

comparison README.md @ 126:d851f4f89fb4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 22f0158e5848
children 88b2480e271a
comparison
equal deleted inserted replaced
125:d79176062baa 126:d851f4f89fb4
17 [4]: https://www.gnu.org/software/octave 17 [4]: https://www.gnu.org/software/octave
18 18
19 19
20 20
21 ## Development 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 22
54 ### Getting the sources 23 ### Getting the sources
55 24
56 Anyone is free to clone this development repository, simply type 25 Anyone is free to clone this development repository, simply type
57 26
73 To build the static website, you need to install [Jekyll][6] and a few more 42 To build the static website, you need to install [Jekyll][6] and a few more
74 tools from [Rubygems][7]. Just type 43 tools from [Rubygems][7]. Just type
75 44
76 gem install jekyll pygments.rb 45 gem install jekyll pygments.rb
77 46
47 A small prerequisite check is performed, by Typing
48
49 make check_prerequisites
50
78 For the responsive webpages, we internally use the [Foundation 5][8] 51 For the responsive webpages, we internally use the [Foundation 5][8]
79 framework. All necessary files are already included inside the 52 framework. All necessary files are already included inside the
80 [hg development repository][2]. 53 [hg development repository][2].
81 54
55 [6]: https://jekyllrb.com/
82 [7]: https://rubygems.org/ 56 [7]: https://rubygems.org/
83 [8]: http://foundation.zurb.com/sites/docs/v/5.5.3/ 57 [8]: http://foundation.zurb.com/sites/docs/v/5.5.3/
84 58
85 59
86 60
87 ### Building the static website 61 ### Building the static website locally
88 62
89 All relevant information for Jekyll to build the static website is located 63 All relevant information for Jekyll to build the static website is located
90 in the file `_config.yml`. 64 in the file `_config.yml`.
91 Typing 65 Typing
92 66
110 84
111 jekyll build --config _config.yml,_config_test.yml 85 jekyll build --config _config.yml,_config_test.yml
112 86
113 87
114 88
115 ### Typical development tasks 89 ### Add a new RSS post
116 90
117 - **Add a new RSS post** 91 Duplicate another post in the subdirectory `_posts` and adjust the filename,
92 especially the date.
118 93
119 Duplicate another post in the subdirectory `_posts` and 94 **Be sure to choose the correct categories!!**
120 adjust the filename, especially the date.
121 95
122 **Be sure to choose the correct categories!!** 96 `categories: news` is reserved for release announcements, that are also
123 97 displayed inside the GUI. Consider choosing another category like
124 `categories: news` is reserved for release announcements, that are also 98 `categories: other` or alike for less important news.
125 displayed inside the GUI. Consider choosing another category like
126 `categories: other` or alike for less important news.
127 99
128 100
129 101
130 ## Deploying 102 ### Deploying the static website online
131 103
132 After building the static website from [web-octave][2] into the 104 For this step you need to have writing permissions to the [Savannah CVS][3]
133 the subdirectory `_site` using Jekyll it can be deployed at the 105 repository. Usually, it should suffice to type
134 [Savannah CVS][3] repository to become visible to the world.
135 106
136 Therefore, checkout the [Savannah CVS][3] repository somewhere 107 make deploy
137 outside the [web-octave][2] directory, typing
138 108
139 export CVS_RSH=ssh 109 if anything doesn't work as expected, look at the provided `Makefile` and
140 cvs -z3 -d:ext:<Savannah account>@cvs.savannah.gnu.org:/web/octave checkout -P octave 110 perform the steps on your own manually, if necessary.
141
142 Now the following steps are required for deployment
143 (see [here][9] and [here][10] for some introduction to CVS):
144
145 1. **DO THIS CAREFULLY!!!** If unsure, start with 2.
146
147 Remove all previous files in the target directory,
148 *but no directories at all or CVS related stuff*!
149 This is due to a [limitation of CVS][11].
150
151 find <DIR> -type f -not -path "*/CVS/*" -exec rm -f '{}' \;
152
153 2. Now copy the new content of [web-octave][2] subdirectory `_site` into the
154 [Savannah CVS][3] repository.
155
156 3. Then in the [Savannah CVS][3] repository:
157
158 cd octave
159
160 1. Remove all no longer existent files
161
162 cvs remove
163
164 2. Add all potential new directories to CVS
165
166 find . -type d -not -name "CVS" -exec cvs add '{}' \;
167
168 3. Add all potential new files to CVS (the [following command][12]
169 proved to me fast)
170
171 find . -type f | grep -v CVS | xargs cvs add
172
173 4. Commit the chages to get online
174
175 cvs commit
176
177 Now everything should be visible to the world.
178
179 [9]: https://savannah.nongnu.org/projects/cvs
180 [10]: http://www.cs.umb.edu/~srevilak/cvs.html
181 [11]: https://web.archive.org/web/20140629054602/http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_7.html#SEC69
182 [12]: http://stackoverflow.com/questions/5071/how-to-add-cvs-directories-recursively