Mercurial > web-octave
annotate README.md @ 235:96aef157a397
* Gemfile.lock: Bundle update
| author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
|---|---|
| date | Sun, 24 Jan 2021 14:53:37 +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. |