blob: bf9d7adb57c0206a3912448d64c08d9f84e85452 (
plain)
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
|
RTEMS Documentation Web Site
============================
Chris Johns <chrisj@rtems.org>
13th Sep 2017
The following documents the RTEMS documentation website.
Jail Access
-----------
The RTEMS Documentation website is a jail on services2.rtems.org.
Login into services2.rtems.org:
$ ssh -A chrisj@services2.rtems.org
Change to root to exec a shell in the jali:
[chrisj@service2 ~]$ jls
JID IP Address Hostname Path
1 140.211.10.142 lists.rtems.org /usr/local/jail/lists.rtems.org
2 140.211.10.143 git.rtems.org /usr/local/jail/git.rtems.org
4 140.211.10.145 www.rtems.org /usr/local/jail/www.rtems.org
5 140.211.10.146 devel.rtems.org /usr/local/jail/devel.rtems.org
6 140.211.10.150 dispatch.rtems.org /usr/local/jail/dispatch.rtems.org
7 140.211.10.153 qualification.rtems.org /usr/local/jail/qualification.rtems.org
8 140.211.10.144 docs.rtems.org /usr/local/jail/docs.rtems.org
[chrisj@service2 ~]$ su
Password:
root@service2:/home/chrisj # jexec 8 /bin/sh
# su - chrisj
docs#
Locations
---------
The website configuration is:
/usr/local/etc/apache24/vhost/docs.rtems.org.conf
The web pages are under:
/data/www/docs.rtems.org
Website
-------
The website is held in the publically avaliable personal repo called
`rtems-admin.git`. To update the website clone the repo:
# git clone git://git.rtems.org/chrisj/rtems-admin.git
Build the website with the prefix being the location of the website in the
jail:
# cd rtems-admin/docs.rtems.org/
# ./waf confgure --prefix=/data/www/docs.rtems.org
# ./waf
To install the website do a waf install:
# ./waf install
You can create a test website on a local machine with a suitable prefix. If you
download and install the various release packages you will be able to loaded
that documentation.
The website is a mix of preset HTML and XML files called catalogues. A
catalogue describes a documentation set and the website's Javascript that is
loaded into user's browsers reads these confguration files from the server and
dynamically creates the various web pages.
There is specific HTML pieces that detail what is loaded on what pages. This
hybrid mix lets us generate new documentation tarballso on a per commit basis
and the website does need to be updated to reflect any local documentation repo
changes.
The HTML needs to be regenerated when a new release is made or a new release
branch is created. This is not often and the over head to do is small.
Legacy Documentation
~~~~~~~~~~~~~~~~~~~~
The lagacy documentation has been fitted into the new website by the website
providing XML catalogue files for each release. These catalogues are generate
when the website is built by waf. The configuration of these websites is held
in configuration.ini. This dats is static and will not change so generating the
website this way means a consistent user interface for what is old
documentation.
ReST Documentation
~~~~~~~~~~~~~~~~~~
The current documentation creates a catalogue and it is the catalogue being
part of the documentation that gives us the needed flexibility. The
documentation also contains an HTML coverpage which is based on the
docs.rtems.org website so the look and feel is consistent.
Configuration
~~~~~~~~~~~~~
The configuration.ini files is a number of sections. The following describes
the sections.
The `latest` section defines the latest release and the release key number be
present in the `releases` section.
The `branches` section describes the branches we are tracking. The key is the
name we used on the website and the value is the git label (I think). There
must be a valid catalogue int the directory `branches/[branch]` where
`[branch]` is the listed branch on the website. Scripts supporting the website
manage the uploading of a branch update to the website.
The `releases` section defines all releases where the key is the release label
and the value is the releases directory. This is the directory in the release
tarball. If you look at the releases you can see how this has evolved and an
error or two.
The `titles` section is collection of all titles for the manual parts in all
the documentation. It is a common location for the naming so we get a
consistent interface for the user.
The remaining sections define each release. The 4.11 and later releases are
nothing more than a `legacy` set to `no`. The documentation package's catalogue
holds all the information.
For legacy documentation you need to create a per release section which is the
value field in the releases section. You can specify a template which as each
release stream is the same. The PDF and HTML paths need to because they vary
and with some errors there is no specific pattern. Finally the manual mix
varies between major releases so a list of manuals that are present needs to be
provided.
Website Updating
----------------
The website is updated by documentation built outside of the docs.rtems.org
jail. There is no sphinx or Tex installed.
Releases are handled manually by updating the website repo, pulling in the
changes, building it and then installing it as root. The documentation needs to
be installed by hand up downloaded the release's tarball and then installing it
to the releases directory.
Note, 4.11.1 does not have a suitable catalogue so I created one.
Updating branches currently requires 3 machines, a machine to build the
documentation, the RTEMS FTP server to upload the tarball too and the
docs.rtems.org machine to download the built tarball and to install the files.
To complicate things more uploading to the FTP server is via SSH and currently
I am using a key with a passphase. I am considering a key without a passphase
which is limited to running rsync.
The scripts used are held with this README and are broken down in pieces to
allow easy testing and also flexibility to handle different path ways into
machines.
Building and Uploading
~~~~~~~~~~~~~~~~~~~~~~
The documentation is built on sync.rtems.org, a jail running on
builder1.rtems.org.
To build the documentation clone the RTEMS Administration repo:
# git clone git://git.rtems.org/chrisj/rtems-admin.git
Change the documentation builder directory:
# cd rtems-admin/doc/builder
The RTEMS documentation uses sphinx to build it and the best way to manage
sphinx is to use a virtual environment. Create the virtualenv by:
# virtualenv docs_builder
Activate the virtual environment:
# source docs_builder/bin/activate
Install sphinx:
(docs_builder) # pip install sphinx
(docs_builder) # pip install sphinxcontrib-bibtex
Finally deactivate the virtual environment:
(docs_builder) # deactivate
Run a test build with:
# $PWD/rtems-docs-build-cron
The built files will be placed in the handover directory on ftp.rtems.org. If
there are any issues check `latest/build.log` for details.
The cron job on the publishing machine runs two scripts. The first is
`rtems-docs-build-branches`. It builds each branch that has changed and
packages the changes into a tarball. It also generates a tag file containing
the branch and hash for each branch in the package. The second script is
`rtems-docs-upload`. It moves the tags file and built output to the FTP
server's handover directory.
Add `rtems-docs-build-cron` as a cron job every 5 minute, depending on the
time it takes to build the documentation.
Downloading and Publishing
~~~~~~~~~~~~~~~~~~~~~~~~~~
The `rtems-docs-cron` is a top level script that runs every 5 minutes. It
downloads then publishes any changes.
The `rtems-docs-download` script copies the tags file from the FTP server and
checks each tag again the tags currently published. If there is a difference in
the file package is downloaeded and the branches unpacked.
The script `rtems-docs-unpack-branches` unpacks the new documentation and
creates a new branches website by selecting the new documentation if the tag's
hash does not match or the current documentation. A new updated tags file is
created.
The `rtems-docs-publish` checks for a new branches website and if present it
removes the current one and copies in the new one.
|
