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