Mercurial > web-octave
annotate README.md @ 264:0c8946d31bc9
* Gemfile.lock: Bundle update
author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
---|---|
date | Thu, 14 Oct 2021 21:52:04 +0900 |
parents | 0c24e49c860f |
children | c90fdd9f5b86 |
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 |
222 | 3 This is the <https://www.octave.org> 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 |
222 | 7 1. The website is developed at two synchronized locations: |
8 - <https://hg.octave.org/web-octave> (Mercurial) | |
9 - <https://github.com/gnu-octave/gnu-octave.github.io> (Git) | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
10 |
222 | 11 2. Static HTML pages are generated from these repositories |
12 and deployed at | |
13 - <https://web.cvs.savannah.gnu.org/viewvc/octave/?root=octave> (Savannah) | |
14 - <https://gnu-octave.github.io/> (GitHub Pages) | |
15 | |
16 3. The deployment to GitHub Pages happens automatically by pushing to the | |
17 respective repository. The deployment on Savannah is more complicated and | |
18 described below in detail and is visible at <https://www.octave.org> that | |
19 redirects to <https://www.gnu.org/software/octave>. | |
94
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 |
222 | 22 ## Simple website changes / contributions |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
23 |
211
a3ad764ca547
* README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
183
diff
changeset
|
24 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
|
25 |
222 | 26 git clone https://github.com/gnu-octave/gnu-octave.github.io.git |
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. |
222 | 30 |
31 If you want submit changes/additions, please create a | |
32 [**pull request**](https://docs.github.com/en/github/getting-started-with-github/github-glossary#pull-request) | |
33 on GitHub or contact the Octave developers at <https://octave.discourse.group/>. | |
34 | |
35 > **Note:** Changes made to the GitHub page repository are only visible there. | |
36 > To change <https://www.octave.org>, the Savannah CVS repository must be | |
37 > updated (see below). | |
38 | |
39 | |
40 ### Add a new RSS post | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
41 |
222 | 42 Duplicate another post in the subdirectory `_posts` and adjust the filename, |
43 especially the date. | |
44 | |
45 **Be sure to choose the correct categories!!** | |
46 | |
47 `categories: news release` is reserved for release announcements, those posts | |
48 are also displayed inside the Octave GUI. Consider choosing another category | |
49 like `categories: news` or alike for less important news. | |
50 | |
51 | |
52 ## Advanced development | |
53 | |
54 ### Synchronize Mercurial and GitHub repositories | |
55 | |
56 You need writing permissions to the Mercurial repository | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
57 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
58 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
|
59 |
222 | 60 Add to `.hg/hgrc` |
61 | |
62 [paths] | |
63 default = ssh://gnuoctave@hg-new.octave.org/hg/web-octave | |
64 github = git+ssh://git@github.com:gnu-octave/gnu-octave.github.io.git | |
94
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 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
67 ### Building requisites |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
68 |
222 | 69 To build the static website offline, you need to install [Ruby][] and |
70 [Bundler][]. For Debian/Ubuntu please perform the following setup fist. | |
71 For other Linux distributions this command might change. | |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
72 |
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
73 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
|
74 |
183
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
75 gem install bundler |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
76 |
183
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
77 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
|
78 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
|
79 |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
80 bundle install |
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
81 |
222 | 82 from within the checked-out website development repository (Mercurial or |
83 GitHub). | |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
84 |
222 | 85 For the responsive webpages, we internally use the [Foundation 6][Foundation] |
86 framework. All necessary files are already included inside this website | |
87 development repository. | |
101
6271c701830d
Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
96
diff
changeset
|
88 |
222 | 89 [Ruby]: https://www.ruby-lang.org/ |
90 [Bundler]: https://bundler.io/ | |
91 [Foundation]: https://get.foundation/sites/docs/ | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
92 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
93 |
222 | 94 ### Building the static website offline |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
95 |
183
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
96 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
|
97 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
|
98 |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
99 bundle exec jekyll build |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
100 |
211
a3ad764ca547
* README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
183
diff
changeset
|
101 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
|
102 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
|
103 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
|
104 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
105 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
|
106 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
|
107 |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
108 bundle exec jekyll serve |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
109 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
110 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
|
111 file changes. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
112 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
113 |
222 | 114 ### Deploying the static website online at Savannah CVS |
119
22f0158e5848
doc: Document rule about categories for posts.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
115
diff
changeset
|
115 |
222 | 116 For this step you need to have writing permissions to the Savannah CVS |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
117 repository. Usually, it should suffice to type |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
118 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
119 make deploy |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
120 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
121 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
|
122 perform the steps on your own manually, if necessary. |