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
|
Welcome to Help for Ubuntu devices!
===================================
What are we doing here?
-----------------------
In a conversation amongst Ubuntu phone enthusiasts, we decided we wanted to
create a good way in which we can aggregate information, tips and tricks and
suggestions for using Ubuntu devices (like the phone or a tablet) easily.
The end result being new Ubuntu users who can
* find out more about how to use their phone
* quickly be more productive
* find new things
* get started easily because the information is available in their language
Thanks a lot for your interest in helping out!
How does this all work?
-----------------------
Our work-flow is a bit special, so bear with us for a while. If you just want
to start adding content, skip this section. The sections below should
probably be enough for that.
We had a couple of requirements when we started this project:
* easy to add/modify content (we decided to use Markdown)
* easy to translate content (we decided to use Launchpad)
* easy to create different builds (one for the phone, one for an online
site, like *.ubuntu.com)
On the way to implementing all of the above, we settled on a mixture of
pelican and po4a on the content side, the Ubuntu HTML5 UI toolkit and
the Ubuntu Web Guidelines on the display side.
* po4a is used to extract translatable messages from the Markdown
content, so that we can get .pot and .po files which are understood by
Launchpad. We also use po4a to generate translated Markdown files.
* pelican takes care of generating HTML from the translated Markdown
files. It can build into different output directories, using different
themes, which is very handy in our case.
* The Ubuntu HTML5 UI toolkit is used for the phone app.
* The Ubuntu Web Guidelines for the build which we will put up on an
Ubuntu site very soon.
Directory structure
-------------------
├── app ← Everything related to the devices app.
│ └── www ← The viewable content of the app.
├── edit-here
│ ├── content
│ │ └── pages ← Here is the place to edit the content.
│ ├── po ← Translations.
│ ├── tests ← Code for automated testing goes here.
│ └── themes ← Themes files, both templates and css/js.
│ ├── phone ← Phone/device app theme.
│ └── web ← Online build (.ubuntu.com) theme.
└── web ← The viewable content of of the online build.
Note: Everything in ./app/www and ./web/ is automatically generated.
Edit content in ./edit-here/content/pages/ and edit themes in
./edit-here/themes/.
Prerequisites
-------------
Note: if you are still on anything before vivid (15.04) (ie: trusty, utopic,
etc.), please add the following PPA:
sudo add-apt-repository ppa:ubuntu-touch-coreapps-drivers/collection
sudo apt update
This is necessary because we need at least pelican 3.5.0. From thereon
the following steps should be smooth sailing.
Before you get started, run:
sudo apt install python-pelican po4a make bzr \
ubuntu-html5-ui-toolkit python3-polib python3-magic \
python3-markdown
This will install the necessary files, so you can build the app or web build
locally and check if your changes actually make sense and look and work well.
Editing
-------
This app is structured in a very simple way. All the content is and all your
edits happen in
./edit-here/content/pages/
The markup for the text is Markdown, which is very easy to learn. Just have
a look at http://daringfireball.net/projects/markdown/ and some of the
existing files to get started.
Once you're happy with your edits, change to the top-level directory and run
make html
This will also generate translated pages.
You can find the updated HTML in ./app/www/. For instance, you can browse
the site in firefox with
firefox app/www/index.html
Creating a click
----------------
To create a click package (for example, if you want to test it on your
device), just run
make click
in the top-level directory.
Publishing it on the web
------------------------
We also want to publish this information on the web. To start a 'web' build
of the content, just run
make web
Find the resulting files in ./web in the top-level directory.
We plan to make use of
http://www.w3.org/International/questions/qa-apache-lang-neg for publishing
this on the web.
Testing
-------
We love automated testing! We added a couple of test cases to
./edit-here/tests/
and it would be great if you added more. We want to run these tests
whenever we build the package or publish the docs or whatever else. Just
to make sure that everything works fine. To run the test suite, run:
make check
Code, bugs, etc.
----------------
To file bugs, or view/submit merge proposals, simply use this project in
Launchpad:
https://launchpad.net/help-app
To update the .pot file, simply run the following command in the edit-here/
directory:
make update-pot
If you want to get help with the app or anything else, ask the fine folks
in #ubuntu-app-devel - for example dholbach, balloons or dpm.
Thanks a lot for helping out!
|