Mercurial > web-octave

annotate README.md @ 156:3ecaed4b95e8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* _includes/footer.html: Web page repo does currently not support https.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Tue, 14 Aug 2018 10:51:08 +0200
parents aaf612aece2b
children 7a664b44fd8d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.