doc.adoc 1.25 KB
Newer Older
Sergey Litvinov's avatar
minor    
Sergey Litvinov committed
1
= documentation
Sergey Litvinov's avatar
Sergey Litvinov committed
2
3
:lext: .adoc

Lucas Amoudruz's avatar
Lucas Amoudruz committed
4
5
6
7
8
9
10
The `uDeviceX` documentation is written in `Asciidoc` format and converted to `html`.
This operation requires link:https://asciidoctor.org/[asciidoctor] (converter to html) and
link:http://pygments.org/[pygments.rb] (for code highlighting).

== installation

=== Mac OS X
Sergey Litvinov's avatar
Sergey Litvinov committed
11

Athena Economides's avatar
Athena Economides committed
12
13
14
15
16
17
[source,sh]
----
gem install asciidoctor
gem install pygments.rb
----

Lucas Amoudruz's avatar
Lucas Amoudruz committed
18
=== Arch linux
Sergey Litvinov's avatar
Sergey Litvinov committed
19
20
21
22

[source,sh]
----
sudo pacman -S asciidoctor
Sergey Litvinov's avatar
minor    
Sergey Litvinov committed
23
gem install pygments.rb
Sergey Litvinov's avatar
Sergey Litvinov committed
24
----
Lucas Amoudruz's avatar
Lucas Amoudruz committed
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

== build

When writing documentation, it is useful to build it and view it on a
local server.

From `doc/`:

[source, sh]
----
./tools/start # <1>
./tools/view  # <2>
./tools/stop  # <3>
----
<1> start a local server (to be done only once)
<2> open the main page in browser from local server
<3> stop the local server


[source, sh]
----
./configure # <1>
make -j     # <2>
----
<1> make dependencies (to be run after adding a file to documentation)
<2> build documentation for local server

== Deploy

Lucas Amoudruz's avatar
Lucas Amoudruz committed
54
55
56
57
58
The deploy command cleans, builds and pushes the documentation on
github pages https://github.com/amlucas/udoc.
The commit message on the udoc repository points on the current
`uDeviceX` commit. It is preferable to have a clean local repository
before deploying:
Lucas Amoudruz's avatar
Lucas Amoudruz committed
59
60
61

[source, sh]
----
Lucas Amoudruz's avatar
Lucas Amoudruz committed
62
git clean -xdf
Lucas Amoudruz's avatar
minor    
Lucas Amoudruz committed
63
./tools/deploy
Lucas Amoudruz's avatar
Lucas Amoudruz committed
64
65
----