web-octave: README.md annotate

annotate README.md @ 182:7a664b44fd8d

Use Bundler for consistent development environment with Jekyll. * README.md: Update documentation for new development workflow * Makefile: Remove custom tool version checks. * _config.yml: Adapt to Bundler workflow. * Gemfile: Document requirements for Bundler. * Gemfile.lock: Document currently used tool versions for Bundler.

author	Kai T. Ohlhus <k.ohlhus@gmail.com>
date	Wed, 20 May 2020 14:05:39 +0900
parents	3ecaed4b95e8
children	ff5b4e46fe3d

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
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	42 To build the static website, you need to install [Jekyll][6] and [Bundler][7].
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
7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	48 Then install the required tools
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	49
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	50 gem install jekyll bundler
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	51
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	52 From now on, almost everything is handled by Bundler. Install all required
7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	53 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	54
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	55 bundle install
7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	56
7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	57 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	58
101 6271c701830d Document the usage of the foundation 5 framework. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 96 diff changeset	59 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	60 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	61 [hg development repository][2].
6271c701830d Document the usage of the foundation 5 framework. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 96 diff changeset	62
126 d851f4f89fb4 Improve Makefile deployment mechanism. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 119 diff changeset	63 [6]: https://jekyllrb.com/
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	64 [7]: https://bundler.io/
136 aaf612aece2b Use https URLs where possible Mike Miller <mtmiller@octave.org> parents: 129 diff changeset	65 [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	66
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	67
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	68
126 d851f4f89fb4 Improve Makefile deployment mechanism. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 119 diff changeset	69 ### Building the static website locally
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	70
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	71 All relevant information for Jekyll and Bundler to build the static website are
7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	72 located in the files `_config.yml`, `Gemfile`, and `Gemfile.lock`.
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	73 Typing
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	74
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	75 bundle exec jekyll build
31 beb4387a8937 Create README.md Alex Krolick <whokilledtheelectricmonk@gmail.com> parents: diff changeset	76
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	77 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	78 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	79 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	80
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	81 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	82 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	83
182 7a664b44fd8d Use Bundler for consistent development environment with Jekyll. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 156 diff changeset	84 bundle exec jekyll serve
94 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 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	87 file changes.
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	88
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	89
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 ### Add a new RSS post
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 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	94 especially the date.
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	95
126 d851f4f89fb4 Improve Makefile deployment mechanism. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 119 diff changeset	96 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	97
129 88b2480e271a Newsfeed: Introduce category "release" to mark very important news. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 126 diff changeset	98 `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	99 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	100 `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	101
e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	102
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 ### Deploying the static website online
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	105
126 d851f4f89fb4 Improve Makefile deployment mechanism. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 119 diff changeset	106 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	107 repository. Usually, it should suffice to type
31 beb4387a8937 Create README.md Alex Krolick <whokilledtheelectricmonk@gmail.com> parents: diff changeset	108
126 d851f4f89fb4 Improve Makefile deployment mechanism. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 119 diff changeset	109 make deploy
94 e8fc61e077fc Merged closed branch "kai" into default. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 31 diff changeset	110
126 d851f4f89fb4 Improve Makefile deployment mechanism. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 119 diff changeset	111 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	112 perform the steps on your own manually, if necessary.

Mercurial > web-octave

annotate README.md @ 182:7a664b44fd8d