Mercurial > web-octave

annotate README.md @ 211:a3ad764ca547

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* README.md: Update developer description.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Fri, 10 Jul 2020 00:41:14 +0900
parents ff5b4e46fe3d
children 0c24e49c860f
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
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
15 [2]: https://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
211
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
25 Anyone is free to clone this website development repository, simply type
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
26
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
27 hg clone https://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
211
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
31 https://octave.discourse.group/.
94
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
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
42 To build the static website, you need to install [Ruby][6] and [Bundler][7].
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
43 For Debian/Ubuntu please perform the following setup fist. For other Linux
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
44 distributions this command might change.
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
45
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
46 sudo apt-get install ruby-full build-essential zlib1g-dev
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
47
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
48 gem install bundler
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
49
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
50 From now on, everything is handled by Bundler. Install all required
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
51 dependencies for the static Octave website by running
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
52
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
53 bundle install
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
54
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
55 from within the checked-out [hg development repository][2].
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
56
211
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
57 For the responsive webpages, we internally use the [Foundation 6][8]
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
58 framework. All necessary files are already included inside this
101
6271c701830d Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 96
diff changeset
59 [hg development repository][2].
6271c701830d Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 96
diff changeset
60
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
61 [6]: https://www.ruby-lang.org/
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
62 [7]: https://bundler.io/
211
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
63 [8]: https://get.foundation/sites/docs/
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
64
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
65
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
66
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
67 ### Building the static website locally
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
68
183
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
69 All relevant information for Bundler to build the static website are located in
ff5b4e46fe3d Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 182
diff changeset
70 the files `_config.yml`, `Gemfile`, and `Gemfile.lock`. Typing
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
71
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
72 bundle exec jekyll build
31
beb4387a8937 Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff changeset
73
211
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
74 from the repository root directory will build a complete static website
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
75 into the subdirectory `_site` using this information. This directory is
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
76 ignored by Mercurial and will be created on first build.
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
77
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
78 Especially for development, it is beneficial to watch the changes locally
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
79 before pushing any changes. Jekyll provides a local webserver by typing
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
80
182
7a664b44fd8d Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 156
diff changeset
81 bundle exec jekyll serve
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
82
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
83 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
84 file changes.
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
85
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
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
88 ### Add a new RSS post
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
89
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
90 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
91 especially the date.
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
92
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
93 **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
94
129
88b2480e271a Newsfeed: Introduce category "release" to mark very important news.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 126
diff changeset
95 `categories: news release` is reserved for release announcements, those posts
211
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
96 are also displayed inside the Octave GUI. Consider choosing another category
a3ad764ca547 * README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 183
diff changeset
97 like `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
98
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
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
101 ### Deploying the static website online
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
102
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
103 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
104 repository. Usually, it should suffice to type
31
beb4387a8937 Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff changeset
105
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
106 make deploy
94
e8fc61e077fc Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 31
diff changeset
107
126
d851f4f89fb4 Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents: 119
diff changeset
108 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
109 perform the steps on your own manually, if necessary.