]>
Commit | Line | Data |
---|---|---|
22b0b166 DM |
1 | Proxmox VE Documentation |
2 | ======================== | |
8e6e6411 | 3 | include::attributes.txt[] |
22b0b166 | 4 | |
0c36e360 | 5 | We try to generate high quality documentation for |
8ff3e5f7 | 6 | {website}[{pve}], and choose to use |
a1ada598 DM |
7 | http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format. |
8 | ||
0c36e360 DM |
9 | The basic idea is to generate high quality manual pages, and assemble |
10 | them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE | |
a1ada598 DM |
11 | Administration Guide]. So we have one source, and generate several |
12 | documents from that. It is also possible to generate printable PDF | |
128b18c0 | 13 | files, or ebook formats ('.epub'). |
22b0b166 | 14 | |
0c36e360 DM |
15 | When possible, we provide scripts to extract API definitions, |
16 | configuration or command line options from the source code. | |
17 | ||
18 | To simplify the documentation task, we keep all Documentation within | |
7aacca6f DM |
19 | this repository. It is possible to generate the docs without installing |
20 | any additional Proxmox packages with: | |
0c36e360 | 21 | |
8ace7110 | 22 | make index |
0c36e360 | 23 | |
7aacca6f DM |
24 | To update the auto-generate API definitions use: |
25 | ||
26 | make update | |
27 | ||
28 | NOTE: you need a fully installed development environment for that. | |
29 | ||
8ace7110 DM |
30 | |
31 | Debian Packages | |
32 | --------------- | |
33 | ||
34 | We generate a development package called 'pve-doc-generator', which is | |
35 | used by other Proxmox VE package to generate manual pages at package | |
36 | build time. | |
37 | ||
38 | Another package called 'pve-docs' is used to publish generated | |
39 | '.html' and '.pdf' files on our web servers. You can generate | |
9d17dbac | 40 | those Debian packages using: |
8ace7110 DM |
41 | |
42 | make deb | |
0c36e360 DM |
43 | |
44 | ||
8e6e6411 DM |
45 | Common Macro definition in link:attributes.txt[] |
46 | ------------------------------------------------ | |
47 | ||
48 | 'asciidoc' allows us to define common macros, which can then be | |
49 | referred to using `{macro}`. We try to use this mechanism to improve | |
50 | consistency. For example, we defined a macro called `pve`, which | |
8ff3e5f7 FG |
51 | expands to "Proxmox VE". |
52 | ||
53 | For URLs which are used more than once, two macros should be defined: | |
54 | ||
55 | * `{name-url}`, which just contains the http(s) URL | |
56 | * `{name}`, which contains the complete link including the canonical | |
57 | description | |
58 | ||
59 | For example, the macro `{forum-url}` expands to {forum-url}, and the macro | |
60 | `{forum}` expands to {forum}. | |
61 | ||
62 | The plan is to add more such definitions for terms which are used more than once. | |
63 | ||
64 | WARNING: When asciidoc encounters a misspelled macro name, it will silently drop | |
65 | the containing line! | |
66 | ||
67 | WARNING: Never use macros in document titles or the ``NAME'' section of man pages, | |
68 | as these get parsed before the `attributes.txt` file gets included. | |
8e6e6411 | 69 | |
578a3111 DM |
70 | Autogenerated CLI Command Synopsis |
71 | ---------------------------------- | |
72 | ||
73 | We generate the command line synopsis for all manual pages | |
74 | automatically. We can do that, because we have a full declarative | |
75 | definition of the {pve} API. I added those generated files | |
76 | ('*-synopsis.adoc') to the git repository, so that it is possible to | |
77 | build the documentation without having a fully installed {pve} | |
78 | development environment. | |
22b0b166 | 79 | |
d067c2ad FG |
80 | Style Guide |
81 | ----------- | |
82 | ||
83 | 'asciidoc' uses a fairly simple markup syntax for formatting content. | |
84 | The following basic principles should be followed throughout our | |
85 | documentation. | |
86 | ||
87 | ||
88 | Sections | |
89 | ~~~~~~~~ | |
90 | ||
91 | Sections are formatted using `two-line titles', by adding a line of | |
92 | the appropriate characters and of the same length as the section title | |
93 | below the title text: | |
94 | ||
95 | Level 0 (top level): ====================== | |
96 | Level 1: ---------------------- | |
97 | Level 2: ~~~~~~~~~~~~~~~~~~~~~~ | |
98 | Level 3: ^^^^^^^^^^^^^^^^^^^^^^ | |
99 | Level 4 (bottom level): ++++++++++++++++++++++ | |
100 | ||
9d17dbac | 101 | Section titles should always be preceded by two empty lines. Each word |
d067c2ad FG |
102 | in a title should be capitalized except for ``articles, coordinating |
103 | conjunctions, prepositions, and the word to in infinitives unless they | |
104 | appear as the first or last word of a title'' (see | |
105 | http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]). | |
106 | ||
107 | ||
108 | Lists | |
109 | ~~~~~ | |
110 | ||
111 | Numbered Lists | |
112 | ^^^^^^^^^^^^^^ | |
113 | ||
114 | Numbered lists should be created using the implicit numbering format: | |
115 | ||
116 | ----- | |
117 | . First level | |
118 | .. Second level | |
119 | . First level again | |
120 | ----- | |
121 | ||
122 | . First level | |
123 | .. Second level | |
124 | . First level again | |
125 | ||
126 | ||
127 | Bulleted Lists | |
128 | ^^^^^^^^^^^^^^ | |
129 | ||
130 | Bulleted lists should be created using the '*' symbol: | |
131 | ||
132 | ----- | |
133 | * First level | |
134 | ** Second level | |
135 | * First level again | |
136 | ----- | |
137 | ||
138 | * First level | |
139 | ** Second level | |
140 | * First level again | |
141 | ||
142 | ||
143 | Labeled Lists | |
144 | ^^^^^^^^^^^^^ | |
145 | ||
146 | Labeled lists should be used to make lists of key-value style text | |
9d17dbac | 147 | more readable, such as command line parameters or configuration options: |
d067c2ad FG |
148 | |
149 | .Regular labeled lists | |
150 | ----- | |
151 | First Label Text:: | |
152 | ||
153 | Element text paragraph | |
154 | ||
155 | Second Label Text:: | |
156 | ||
157 | Another element text paragraph. | |
158 | ----- | |
159 | ||
160 | First Label Text:: | |
161 | ||
162 | Element text paragraph | |
163 | ||
164 | Second Label Text:: | |
165 | ||
166 | Another element text paragraph. | |
167 | ||
168 | .Horizontal labeled lists | |
169 | ----- | |
170 | [horizontal] | |
171 | First Label Text:: Element text paragraph | |
172 | ||
173 | Second Label Text:: Another element text paragraph. | |
174 | ----- | |
175 | ||
176 | creates | |
177 | ||
178 | [horizontal] | |
179 | First Label Text:: Element text paragraph | |
180 | ||
181 | Second Label Text:: Another element text paragraph. | |
182 | ||
183 | The FAQ section uses a special questions and answers style for | |
184 | labeled lists. | |
185 | ||
186 | ||
187 | Text and Block Styles | |
188 | ~~~~~~~~~~~~~~~~~~~~~ | |
189 | ||
190 | 'asciidoc' offers a wide range of default text styles: | |
191 | ||
192 | * 'Emphasized text': created using \'text', used for emphasizing words | |
193 | and phrases | |
194 | * `Monospaced text`: created using \`text`, used for command / program | |
128b18c0 | 195 | names, file paths, in-line commands, option names and values |
d067c2ad FG |
196 | * *Strong text*: created using \*text*, used for emphasizing concepts |
197 | or names when first introduced in a section. | |
198 | ||
128b18c0 | 199 | There are also different built-in block styles that are used in |
d067c2ad FG |
200 | our documentation: |
201 | ||
202 | Complete paragraphs can be included literally by prepending each | |
203 | of their lines with whitespace. Use this for formatting complete | |
204 | commands on their own line, such as: | |
205 | ||
206 | pct set ID -option value | |
207 | ||
208 | ---- | |
209 | By surrounding a paragraph with lines containing at least four '-' | |
210 | characters, its content is formatted as listing. | |
211 | ||
212 | Use this for formatting file contents or command output. | |
213 | ---- | |
214 | ||
215 | Specially highlighted 'notes', 'warnings' and 'important' information | |
216 | can be created by starting a paragraph with `NOTE:`, `WARNING:` or | |
217 | `IMPORTANT:`: | |
218 | ||
219 | NOTE: this is a note | |
220 | ||
221 | WARNING: this is warning | |
222 | ||
223 | IMPORTANT: this is important information | |
224 | ||
225 | For each of these blocks (including lists and paragraphs), a block header | |
226 | can be defined by prepending the block with a `.' character and the header | |
227 | text: | |
228 | ||
229 | ----- | |
230 | .Title of List | |
231 | * First element | |
232 | * Second element | |
233 | * Third element | |
234 | ----- | |
235 | ||
236 | .Title of List | |
237 | * First element | |
238 | * Second element | |
239 | * Third element | |
240 | ||
241 | For example, block headers can be used to add file names/paths to file | |
242 | content listings. | |
243 | ||
244 | ||
22b0b166 DM |
245 | Copyright |
246 | --------- | |
247 | ||
40152dfd | 248 | Copyright (C) 2016 Proxmox Server Solutions Gmbh |
22b0b166 DM |
249 | |
250 | Permission is granted to copy, distribute and/or modify this document | |
251 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
252 | any later version published by the Free Software Foundation; with no | |
f1e6bbae DM |
253 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
254 | copy of the license is included in the link:LICENSE[LICENSE] file. |