]>
Commit | Line | Data |
---|---|---|
22b0b166 DM |
1 | Proxmox VE Documentation |
2 | ======================== | |
3 | ||
0c36e360 | 4 | We try to generate high quality documentation for |
8ff3e5f7 | 5 | {website}[{pve}], and choose to use |
a1ada598 DM |
6 | http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format. |
7 | ||
0c36e360 DM |
8 | The basic idea is to generate high quality manual pages, and assemble |
9 | them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE | |
a1ada598 DM |
10 | Administration Guide]. So we have one source, and generate several |
11 | documents from that. It is also possible to generate printable PDF | |
128b18c0 | 12 | files, or ebook formats ('.epub'). |
22b0b166 | 13 | |
0c36e360 DM |
14 | When possible, we provide scripts to extract API definitions, |
15 | configuration or command line options from the source code. | |
16 | ||
17 | To simplify the documentation task, we keep all Documentation within | |
7aacca6f DM |
18 | this repository. It is possible to generate the docs without installing |
19 | any additional Proxmox packages with: | |
0c36e360 | 20 | |
1de93a7c | 21 | make pve-doc-generator.mk |
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 | ||
a69bfc83 DM |
45 | Common Macro definition in link:asciidoc/asciidoc-pve.conf[] |
46 | ------------------------------------------------------------ | |
8e6e6411 DM |
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 | ||
a69bfc83 DM |
62 | The plan is to add more such definitions for terms which are used more |
63 | than once. | |
8ff3e5f7 | 64 | |
a69bfc83 DM |
65 | WARNING: When asciidoc encounters a misspelled macro name, it will |
66 | silently drop the containing line! | |
8ff3e5f7 | 67 | |
8e6e6411 | 68 | |
578a3111 DM |
69 | Autogenerated CLI Command Synopsis |
70 | ---------------------------------- | |
71 | ||
72 | We generate the command line synopsis for all manual pages | |
73 | automatically. We can do that, because we have a full declarative | |
74 | definition of the {pve} API. I added those generated files | |
75 | ('*-synopsis.adoc') to the git repository, so that it is possible to | |
76 | build the documentation without having a fully installed {pve} | |
77 | development environment. | |
22b0b166 | 78 | |
d067c2ad FG |
79 | Style Guide |
80 | ----------- | |
81 | ||
82 | 'asciidoc' uses a fairly simple markup syntax for formatting content. | |
83 | The following basic principles should be followed throughout our | |
84 | documentation. | |
85 | ||
86 | ||
87 | Sections | |
88 | ~~~~~~~~ | |
89 | ||
90 | Sections are formatted using `two-line titles', by adding a line of | |
91 | the appropriate characters and of the same length as the section title | |
92 | below the title text: | |
93 | ||
94 | Level 0 (top level): ====================== | |
95 | Level 1: ---------------------- | |
96 | Level 2: ~~~~~~~~~~~~~~~~~~~~~~ | |
97 | Level 3: ^^^^^^^^^^^^^^^^^^^^^^ | |
98 | Level 4 (bottom level): ++++++++++++++++++++++ | |
99 | ||
6925e2aa TL |
100 | NOTE: Level 4 headings are currently not working for `manpage` outputs, you may |
101 | want to use `.SECTION' instead, which results in the same rendering, and this | |
102 | level of Heading isn't displayed in any Index/TOC anyway. | |
103 | ||
9d17dbac | 104 | Section titles should always be preceded by two empty lines. Each word |
d067c2ad FG |
105 | in a title should be capitalized except for ``articles, coordinating |
106 | conjunctions, prepositions, and the word to in infinitives unless they | |
107 | appear as the first or last word of a title'' (see | |
108 | http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]). | |
109 | ||
110 | ||
111 | Lists | |
112 | ~~~~~ | |
113 | ||
114 | Numbered Lists | |
115 | ^^^^^^^^^^^^^^ | |
116 | ||
117 | Numbered lists should be created using the implicit numbering format: | |
118 | ||
119 | ----- | |
120 | . First level | |
121 | .. Second level | |
122 | . First level again | |
123 | ----- | |
124 | ||
125 | . First level | |
126 | .. Second level | |
127 | . First level again | |
128 | ||
129 | ||
130 | Bulleted Lists | |
131 | ^^^^^^^^^^^^^^ | |
132 | ||
133 | Bulleted lists should be created using the '*' symbol: | |
134 | ||
135 | ----- | |
136 | * First level | |
137 | ** Second level | |
138 | * First level again | |
139 | ----- | |
140 | ||
141 | * First level | |
142 | ** Second level | |
143 | * First level again | |
144 | ||
145 | ||
cef49180 | 146 | If you need to have other elements on the same level as a list element you |
a4ca3a66 TL |
147 | can do this with the '+' symbol: |
148 | ||
149 | ---- | |
150 | . First level | |
151 | .. Second level | |
152 | + | |
a0f50f26 | 153 | Another Sentence (or Block) on the continued second level. |
a4ca3a66 TL |
154 | . First level again |
155 | ---- | |
156 | ||
157 | . First level | |
158 | .. Second level | |
159 | + | |
a0f50f26 | 160 | Another Sentence (or Block) on the continued second level. |
a4ca3a66 TL |
161 | |
162 | . First level again | |
163 | ||
d067c2ad FG |
164 | Labeled Lists |
165 | ^^^^^^^^^^^^^ | |
166 | ||
167 | Labeled lists should be used to make lists of key-value style text | |
9d17dbac | 168 | more readable, such as command line parameters or configuration options: |
d067c2ad FG |
169 | |
170 | .Regular labeled lists | |
171 | ----- | |
172 | First Label Text:: | |
173 | ||
174 | Element text paragraph | |
175 | ||
176 | Second Label Text:: | |
177 | ||
178 | Another element text paragraph. | |
179 | ----- | |
180 | ||
181 | First Label Text:: | |
182 | ||
183 | Element text paragraph | |
184 | ||
185 | Second Label Text:: | |
186 | ||
187 | Another element text paragraph. | |
188 | ||
189 | .Horizontal labeled lists | |
190 | ----- | |
191 | [horizontal] | |
192 | First Label Text:: Element text paragraph | |
193 | ||
194 | Second Label Text:: Another element text paragraph. | |
195 | ----- | |
196 | ||
197 | creates | |
198 | ||
199 | [horizontal] | |
200 | First Label Text:: Element text paragraph | |
201 | ||
202 | Second Label Text:: Another element text paragraph. | |
203 | ||
204 | The FAQ section uses a special questions and answers style for | |
205 | labeled lists. | |
206 | ||
207 | ||
208 | Text and Block Styles | |
209 | ~~~~~~~~~~~~~~~~~~~~~ | |
210 | ||
211 | 'asciidoc' offers a wide range of default text styles: | |
212 | ||
213 | * 'Emphasized text': created using \'text', used for emphasizing words | |
214 | and phrases | |
215 | * `Monospaced text`: created using \`text`, used for command / program | |
128b18c0 | 216 | names, file paths, in-line commands, option names and values |
d067c2ad FG |
217 | * *Strong text*: created using \*text*, used for emphasizing concepts |
218 | or names when first introduced in a section. | |
219 | ||
128b18c0 | 220 | There are also different built-in block styles that are used in |
d067c2ad FG |
221 | our documentation: |
222 | ||
223 | Complete paragraphs can be included literally by prepending each | |
224 | of their lines with whitespace. Use this for formatting complete | |
225 | commands on their own line, such as: | |
226 | ||
227 | pct set ID -option value | |
228 | ||
229 | ---- | |
230 | By surrounding a paragraph with lines containing at least four '-' | |
231 | characters, its content is formatted as listing. | |
232 | ||
233 | Use this for formatting file contents or command output. | |
234 | ---- | |
235 | ||
236 | Specially highlighted 'notes', 'warnings' and 'important' information | |
237 | can be created by starting a paragraph with `NOTE:`, `WARNING:` or | |
238 | `IMPORTANT:`: | |
239 | ||
240 | NOTE: this is a note | |
241 | ||
242 | WARNING: this is warning | |
243 | ||
244 | IMPORTANT: this is important information | |
245 | ||
246 | For each of these blocks (including lists and paragraphs), a block header | |
247 | can be defined by prepending the block with a `.' character and the header | |
248 | text: | |
249 | ||
250 | ----- | |
251 | .Title of List | |
252 | * First element | |
253 | * Second element | |
254 | * Third element | |
255 | ----- | |
256 | ||
257 | .Title of List | |
258 | * First element | |
259 | * Second element | |
260 | * Third element | |
261 | ||
262 | For example, block headers can be used to add file names/paths to file | |
263 | content listings. | |
264 | ||
54026d6d EK |
265 | |
266 | Online Help | |
267 | ----------- | |
268 | Each {pve} installation contains the full documentation in HTML format, | |
269 | which is then used as the target of various help buttons in the GUI. | |
270 | ||
271 | If after adding a specific entry in the documentation you want to | |
272 | create a help button pointing to that, you need to do the | |
273 | following: | |
274 | ||
275 | * add a string id in double square brackets before your | |
276 | documentation entry, like `[[qm_general_settings]]` | |
277 | * rebuild the `asciidoc-pve` script and the HTML chapter file containing | |
278 | your entry | |
279 | * add a property `onlineHelp` in the ExtJS panel you want to document, | |
280 | using the above string, like `onlineHelp: qm_general_settings` | |
281 | This panel has to be a child class of PVE.panel.InputPanel | |
282 | ||
283 | On calling `make install` the asciidoc-pve script will populate | |
284 | a JS object associating the string id and a link to the | |
285 | local HTML documentation, and the help button of your input panel | |
286 | will point to this link. | |
287 | ||
288 | ||
0d1b9a16 DM |
289 | Screenshots |
290 | ----------- | |
291 | ||
1ff5e4e8 | 292 | [thumbnail="screenshot/gui-datacenter-search.png"] |
0d1b9a16 DM |
293 | |
294 | First, it should be noted that we can display screenshots on 'html' | |
470d4313 DC |
295 | and 'wiki' pages, and we can include them in printed documentation. But |
296 | it is not possible to render them inside manual pages. So screenshot | |
0d1b9a16 DM |
297 | inside manual pages should be optional, i.e. the text should not |
298 | depend on the visibility of the screenshot. You can include a | |
299 | screenshot by setting the 'thumbnail' attribute on a paragraph: | |
300 | ||
301 | ---- | |
1ff5e4e8 | 302 | [thumbnail="screenshot/gui-datacenter-search.png"] |
0d1b9a16 DM |
303 | First, it should be noted ... |
304 | ---- | |
305 | ||
6a6f8374 DM |
306 | The corresponding file need to reside inside folder |
307 | `images/screenshot`, and should be in `.png` image format. We include | |
308 | the screenshots in printed documentation, and 'pdftex' uses the | |
309 | density (DPI) specified inside the file. So all screenshots should use | |
310 | the same density. We currently require the density set to 146 DPI, so | |
311 | that we can display a 1024 pixels wide image. You should not include | |
312 | larger screenshots (although it is possible). | |
313 | ||
314 | You can use the `./png-cleanup.pl` script to set the correct | |
315 | density. Simply use the following command to import a screenshot | |
316 | image: | |
317 | ||
318 | ---- | |
319 | # ./png-cleanup.pl screenshot.png images/screenshot/screenshot.png | |
320 | ---- | |
321 | ||
322 | TIP: You can use `identify -verbose screenshot.png` command to show | |
323 | all image attributes (from debian package 'imagemagick') | |
324 | ||
0d57da18 | 325 | .Default Screenshot Layout |
0d1b9a16 | 326 | |
1ff5e4e8 | 327 | [thumbnail="screenshot/gui-datacenter-search.png"] |
0d57da18 DM |
328 | |
329 | We normally display screenshots as small thumbnail on the right side | |
470d4313 | 330 | of a paragraph. On printed documentation, we render the full sized |
0d57da18 DM |
331 | graphic just before the paragraph, or between the title and the text |
332 | if the paragraph has a title. It is usually a good idea to add a title | |
333 | to paragraph with screenshots. | |
334 | ||
1ff5e4e8 | 335 | [thumbnail="screenshot/gui-datacenter-search.png", float="left"] |
0d57da18 DM |
336 | |
337 | If you need to render many screenshots, it is possible to place them | |
338 | on the left side, so you can alternate the thumbnail position using the | |
339 | `float` attribute: | |
340 | ||
341 | ---- | |
1ff5e4e8 | 342 | [thumbnail="screenshot/gui-datacenter-search.png", float="left"] |
0d57da18 DM |
343 | If you need to render many screenshots ... |
344 | ---- | |
345 | ||
346 | Please avoid to many consecutive screenshots to avoid rendering | |
347 | problems. Also verify the printed documentation to see if large | |
348 | screenshots create layout problems. | |
0d1b9a16 | 349 | |
d067c2ad | 350 | |
22b0b166 DM |
351 | Copyright |
352 | --------- | |
353 | ||
79cfad5d | 354 | Copyright (C) 2016-2021 Proxmox Server Solutions GmbH |
22b0b166 DM |
355 | |
356 | Permission is granted to copy, distribute and/or modify this document | |
357 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
358 | any later version published by the Free Software Foundation; with no | |
f1e6bbae DM |
359 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
360 | copy of the license is included in the link:LICENSE[LICENSE] file. |