blob: 59b69c01d49b0644f5140c42f9a0ac56384a9230 (
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
|
Integrate project specific Documentaion into the Manual
-------------------------------------------------------
PTXdist supports the ability to integrate project specific documentation
into the final PTXdist manual. To do so, PTXdist handles file replacements and
additions, while generating the documentation.
File replacement is working in the same manner like for all other files in
a PTXdist based project: a local file with the same name superseds a global file
from PTXdist.
With this mechanism we can replace existing PTXdist documentation or add new one.
If we want to add a new global section to the manual we can copy the global
PTXdist ``doc/index.rst`` file into our local ``doc/`` directory and adapt it
accordingly.
To change or add things less intrusive we can do it on the various ``*.inc``
files in the PTXdist's ``doc/`` directory which define the content of the
sections.
For example to change the image createn section's content, we can copy the
global PTXdist ``doc/user_images.inc`` into our local ``doc/`` directory and
adapt it to the behaviour of our project.
In the generic documentation source many text uses variables instead of fixed
content. These variables are filled with values extracted from the current PTXdist
project prior building the final documentation. Since PTXdist projects are bound
to a defined PTXdist version and toolchain version, this kind of information is
extracted from the current settings and substituted in the documentation. This
behaviour ensures the documentaiton includes the project's exact definition to
external dependencies.
Refer the PTXdist file ``doc/conf.py`` for more information on variable
substitution. This PTXdist global file can be superseded by a local copy as well.
Requirements to build the Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fonts:
- *Liberation Sans/Liberation Sans Bold* or *DejaVu Sans/DejaVu Sans Bold*
(for the "Portable Document Format", e.g. PDF)
- *Inconsolata*, *DejaVu Sans Mono* or *Liberation Sans Mono*
(for the "Portable Document Format", e.g. PDF)
Tools:
- *Sphinx* version 1.3.4, better 1.4.2 (for all kind of document formats)
- *TeX Live 2016* (for the "Portable Document Format", e.g. PDF)
Building the Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~
PTXdist comes with support to generate *HTML* or *Portable Document Format* based
documentation from the sources.
The command:
::
$ ptxdist docs-html
will build the HTML based documentation into ``Documentation/html`` and the entry
file for this kind of documentation is ``Documentation/html/index.html``.
The command:
::
$ ptxdist docs-latex
will build the Latex based documentation which results into the final
*Portable Document Format* document. This result can be found in
``Documentation/latex/``.
|
