~dholbach/help-app/1434125

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
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
-------------------

.
├── content            ← Here is the place to edit the content.
│   ├── images         ← Images to be used in the docs.
│   └── pages          ← Actual text to be edited.
├── debian             ← Everything related to .deb packaging.
├── internals          ← Build tools, pelican config.
│   ├── tests          ← Code for automated testing.
│   └── translations   ← Python code for handling translations.
├── po                 ← Translations (.pot and po files).
└── static
    ├── app            ← Static files for the click app.
    └── themes         ← Themes files, both templates and css/js.
        ├── app
        └── web

Note: Everything in .build is automatically generated.
      Edit content in ./content/pages/ and edit themes in
      ./static/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 bzrtools \
	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

	./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 app

This will also generate translated pages.

You can find the updated HTML in ./build/app/www/.

To launch the app, you can use ubuntu-html5-app-launcher in the www dir, or
just call

	make launch

(This will also run the 'make app' command for you.)


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 the ./build/web directory.

To update the publishing branch (you need to be member of ~help-app-dev), 
run

	make web-publish

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 

	./internals/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

Running the app on a phone
--------------------------

While you can just generate and install the click package manually,
we recommend the SDK for testing the phone app.

You can run the `make appl` target to generate the HTML files and then
open the app/help.ubuntuhtmlproject file with the Ubuntu SDK IDE.

From there, you can set up a desktop kit to run it on your host,
or a phone kit to run the app on your phone.


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 top-level
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!