Mercurial > web-octave
annotate README.md @ 163:dcc5564ed7ad
Mention that Win-Installers bundle several OF-packages (bug #55588).
* _includes/head.html: Add foundation.alert.js.
* _includes/install.html: Mention that Win-Installers bundle several
OF-packages.
author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
---|---|
date | Tue, 29 Jan 2019 17:08:24 +0100 |
parents | 3ecaed4b95e8 |
children | 7a664b44fd8d |
rev | line source |
---|---|
119
22f0158e5848
doc: Document rule about categories for posts.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
115
diff
changeset
|
1 # GNU Octave Website development |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
2 |
136
aaf612aece2b
Use https URLs where possible
Mike Miller <mtmiller@octave.org>
parents:
129
diff
changeset
|
3 This is the [https://www.octave.org][1] website development repository. |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
4 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
5 The development and deployment workflow in short: |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
6 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
7 1. The website is developed in this [web-octave][2] Mercurial repository. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
8 2. Static HTML pages are generated from this [web-octave][2] repository |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
9 and are deployed at the [Savannah CVS][3] repository. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
10 3. After deploying the static pages, they are visible from |
136
aaf612aece2b
Use https URLs where possible
Mike Miller <mtmiller@octave.org>
parents:
129
diff
changeset
|
11 [https://www.octave.org][1], that redirects to |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
12 [https://www.gnu.org/software/octave][4]. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
13 |
136
aaf612aece2b
Use https URLs where possible
Mike Miller <mtmiller@octave.org>
parents:
129
diff
changeset
|
14 [1]: https://www.octave.org |
156
3ecaed4b95e8
* _includes/footer.html: Web page repo does currently not support https.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
136
diff
changeset
|
15 [2]: http://hg.octave.org/web-octave |
136
aaf612aece2b
Use https URLs where possible
Mike Miller <mtmiller@octave.org>
parents:
129
diff
changeset
|
16 [3]: https://web.cvs.savannah.gnu.org/viewvc/octave/?root=octave |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
17 [4]: https://www.gnu.org/software/octave |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
18 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
19 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
20 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
21 ## Development |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
22 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
23 ### Getting the sources |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
24 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
25 Anyone is free to clone this development repository, simply type |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
26 |
156
3ecaed4b95e8
* _includes/footer.html: Web page repo does currently not support https.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
136
diff
changeset
|
27 hg clone http://hg.octave.org/web-octave |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
28 |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
29 to get anonymous read access without writing privileges. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
30 To push your changes, please contact the octave developers at |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
31 `maintainers@octave.org`. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
32 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
33 If you already have writing permissions for this repository, |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
34 you should clone the repository using |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
35 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
36 hg clone ssh://gnuoctave@octave.org/hg/web-octave |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
37 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
38 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
39 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
40 ### Building requisites |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
41 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
42 To build the static website, you need to install [Jekyll][6] and a few more |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
43 tools from [Rubygems][7]. Just type |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
44 |
96
e7efa40deb17
Fix URLs, Images, Titles to be up with Alex original style.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
94
diff
changeset
|
45 gem install jekyll pygments.rb |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
46 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
47 A small prerequisite check is performed, by Typing |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
48 |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
49 make check_prerequisites |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
50 |
101
6271c701830d
Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
96
diff
changeset
|
51 For the responsive webpages, we internally use the [Foundation 5][8] |
6271c701830d
Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
96
diff
changeset
|
52 framework. All necessary files are already included inside the |
6271c701830d
Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
96
diff
changeset
|
53 [hg development repository][2]. |
6271c701830d
Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
96
diff
changeset
|
54 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
55 [6]: https://jekyllrb.com/ |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
56 [7]: https://rubygems.org/ |
136
aaf612aece2b
Use https URLs where possible
Mike Miller <mtmiller@octave.org>
parents:
129
diff
changeset
|
57 [8]: https://foundation.zurb.com/sites/docs/v/5.5.3/ |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
58 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
59 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
60 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
61 ### Building the static website locally |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
62 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
63 All relevant information for Jekyll to build the static website is located |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
64 in the file `_config.yml`. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
65 Typing |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
66 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
67 jekyll build |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
68 |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
69 from the repositories root directory will build a complete static website |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
70 into the subdirectory `_site` using this information (this directory is |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
71 ignored by Mercurial and will be created on first build). |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
72 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
73 Especially for development, it is beneficial to watch the changes locally |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
74 before pushing any changes. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
75 Jekyll provides a local webserver by typing |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
76 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
77 jekyll serve |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
78 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
79 and rebuilds the whole static website automatically, as it monitors any |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
80 file changes. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
81 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
82 To build the test page, that can be deployed at some subdirectory, e.g. |
136
aaf612aece2b
Use https URLs where possible
Mike Miller <mtmiller@octave.org>
parents:
129
diff
changeset
|
83 `https://www.octave.org/new`, use |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
84 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
85 jekyll build --config _config.yml,_config_test.yml |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
86 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
87 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
88 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
89 ### Add a new RSS post |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
90 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
91 Duplicate another post in the subdirectory `_posts` and adjust the filename, |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
92 especially the date. |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
93 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
94 **Be sure to choose the correct categories!!** |
119
22f0158e5848
doc: Document rule about categories for posts.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
115
diff
changeset
|
95 |
129
88b2480e271a
Newsfeed: Introduce category "release" to mark very important news.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
126
diff
changeset
|
96 `categories: news release` is reserved for release announcements, those posts |
88b2480e271a
Newsfeed: Introduce category "release" to mark very important news.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
126
diff
changeset
|
97 are also displayed inside the GUI. Consider choosing another category like |
88b2480e271a
Newsfeed: Introduce category "release" to mark very important news.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
126
diff
changeset
|
98 `categories: news` or alike for less important news. |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
99 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
100 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
101 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
102 ### Deploying the static website online |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
103 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
104 For this step you need to have writing permissions to the [Savannah CVS][3] |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
105 repository. Usually, it should suffice to type |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
106 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
107 make deploy |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
108 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
109 if anything doesn't work as expected, look at the provided `Makefile` and |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
110 perform the steps on your own manually, if necessary. |