-
Notifications
You must be signed in to change notification settings - Fork 0
/
website_howto.txt
241 lines (173 loc) · 9.42 KB
/
website_howto.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
WEBSITE HOW-TO
Hrothgar, June 2015
Get in touch with [email protected] for questions.
----------------------------------------------------------
Contents.
1. How to install the website on your machine.
2. How to publish an example.
3. How to publish a Guide chapter.
4. How to add a news item.
* * *
1. HOW TO INSTALL THE WEBSITE ON YOUR MACHINE.
The following instruction assumes you do not already have
local copies of the guide and examples repos. If you already have
them, the procedure is different (talk to Anthony).
Download the "chebsite-setup.sh" script from the "chebfun/dev-tools" repo
on GitHub. If you run the chebsite-setup script from a directory called
"my_folder", then the resulting directory structure for the website will
end up looking like this:
my_folder
|-- chebsite-setup.sh
|-- chebsite
| |-- _build
| |-- ...
|-- examples
|-- guide
As you can see, the chebsite-setup script will create a few directories in
the place where it's executed. Two of those directories are for the
examples and guide repos (these are necessary in order to make examples or
publish Guide chapters). The final directory, called "chebsite" by
default, contains the website content and build files, and is tied to the
"chebfun/chebsite" Github repository.
A bit about the structure of the website: the directory "chebsite" itself
contains many Markdown files, some python files, and other content
necessary for the website (images, CSS, and so on). Any changes to the
website -- for instance, adding a news item or modifying the "about" page
-- should be made to Markdown (.md) files in the "chebsite" directory. The
procedure for publishing examples and Guide chapters is discussed below.
After changes are made, the website must be compiled, as per (2.ii) below.
Compiling the website mostly involves transforming the Markdown into HTML.
The output HTML is then stored in the "chebsite/_build" directory, which
is tied to the chebfun/chebfun.github.io repository on Github. (Indeed,
there is a git repo inside another git repo -- there is nothing wrong with
that.)
From there changes must be committed and pushed, as per (2.iii) below.
2. HOW TO PUBLISH AN EXAMPLE.
NOTE. The following detailed procedure is no longer the recommended
method. Chebfun team members have access to a script publish-example.sh
that automates this process, and we recommend use of that instead.
0. Before publishing, you should push the new or revised example to
GitHub in the usual fashion (using branch development). You should
also make sure you have the latest copy of the chebsite scripts and
the website from GitHub:
$ cd chebsite
$ git pull origin master
$ cd _build
$ git pull origin master
If something new from GitHub conflicts with changes (committed or
uncommitted) that you have made locally, these commands will fail,
and you will need to address the conflicts manually.
i. From MATLAB, move to the directory my_folder/chebsite/examples and then
execute the make_example function:
>> cd chebsite/examples
>> make_example('fun', 'HelloWorld')
The final output should say "Done."
ii. From a regular system terminal, move to the "chebsite" directory and
build the website. The script will output the names of all files
modified since the last time you built the website. (The first time
the build script runs, however, there will be a lot of output, since
all the output files are new.) (Indeed, *every* time the build
script runs, a lot of output is produced. Anthony hopes to
discuss this matter with Hrothgar.)
$ python BUILD.py
If you want to see your changes before committing them, run the
SERVE.py script, which runs the website locally on your machine.
$ python SERVE.py
$ open http://localhost:8000/examples
iii. If you're happy with these changes, Ctrl+C out of the server and then
commit your changes. To do this, move to the _build directory and use
git to commit and push.
$ cd _build
$ git status
$ git add examples/*.html examples/fun/*.html examples/fun/img/*.png
$ git add index.html examples/fun/*.m examples/fun/img/*.html
$ git commit -m 'Publishing the example fun/HelloWorld'
Once you have checked everything and want your
changes to go live, push to the master branch of
the website:
$ git push origin master
3. HOW TO PUBLISH A GUIDE CHAPTER.
NOTE. As with publishing examples, the following detailed procedure is no
longer the recommended method. Chebfun team members have access to a script
publish-example.sh that automates this publication of guide chapters as
well as examples, and we recommend use of that instead.
The procedure for publishing a Guide chapter is basically the same as the
procedure for publishing an Example.
0. Before publishing, you should push the new or revised chapter to
GitHub in the usual fashion (using branch development). You should
also make sure you have the latest copy of the chebsite scripts and
the website from GitHub. (See item 0 under "HOW TO PUBLISH AN
EXAMPLE", above.)
i. From MATLAB, move to the directory my_folder/chebsite/docs/guide and
then execute the make_chapters function. The input to the function is
a vector of integers specifying which chapters to publish.
>> cd chebsite/docs/guide
>> make_chapters(2:4) % Publishes chapters 2, 3, and 4.
The final output should say "Done."
ii. The rest of the procedure is the same as for the Example case.
From a regular system terminal, move to the "chebsite" directory and
build the website.
$ python BUILD.py
If you want to see your changes before committing them, run the
SERVE.py script, which runs the website locally on your machine.
$ python SERVE.py
$ open http://localhost:8000/docs/guide
iii. If you're happy with these changes, Ctrl+C out of the server and then
commit your changes. To do this, move to the _build directory and use
git to commit and push.
$ cd _build
$ git status
$ git add docs/guide/*.html docs/guide/img/*.png
$ git commit -m 'Publishing a Guide chapter'
Once you have checked everything and want your
changes to go live, push to the master branch of
the website:
$ git push origin master
4. HOW TO ADD A NEWS ITEM.
To add a news item, create a Markdown file for the news item and then
build the website.
0. Before publishing, you should make sure you have the latest copy of
the chebsite scripts and the website from GitHub. (See item 0 under
"HOW TO PUBLISH AN EXAMPLE", above.)
i. News items are stored in the "chebsite/news" directory. Take a look
at the existing news items for examples. (I usually just copy one of
the existing news items and then make the necessary changes.)
The title of the file must conform to the standard
YYYYMMDD-title-slug.md
in which
* YYYYMMDD is the date attached to the news item (this is simply
the date printed next to the news item's title -- the news item
is not scheduled for future publish if the date is in the
future);
* title-slug is the version of the title that will appear in the
URL of the news item.
Inside the file there is a standard format, too. (All Markdown files
on the website use this format.) Inside the dashed "---" lines there
is some YAML, which is a very simple plaintext format for data. You
will see a "title" field, a "layout" field (which tells the website
what HTML page format to use), and a "snip" field, which contains a
brief summary of the news item for use on e.g. the home page.
After the second dashed "---" line is the body of the news item,
which is formatted using Markdown. You can also insert HTML in the
body if you like (for adding tables for pictures, whatever). Note
that Markdown is not parsed inside of HTML blocks.
ii. Again, the rest of the procedure is the same as before.
From a regular system terminal, move to the "chebsite" directory and
build the website.
$ python BUILD.py
If you want to see your changes before committing them, run the
SERVE.py script, which runs the website locally on your machine.
$ python SERVE.py
$ open http://localhost:8000/news
iii. If you're happy with these changes, Ctrl+C out of the server and then
commit your changes. To do this, move to the _build directory and use
git to commit and push.
$ cd _build
$ git status
$ git add index.html news/*.html
$ git commit -m 'Adding a news item'
$ git push origin master
Once you have checked everything and want your
changes to go live, push to the master branch of
the website:
$ git push origin master