README.adoc

   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 NOTE: Level 4 headings are currently not working for `manpage` outputs, you may
 100 want to use `.SECTION' instead, which results in the same rendering, and this
 101 level of Heading isn't displayed in any Index/TOC anyway.
 102
 103 Section titles should always be preceded by two empty lines. Each word
 104 in a title should be capitalized except for ``articles, coordinating
 105 conjunctions, prepositions, and the word to in infinitives unless they
 106 appear as the first or last word of a title'' (see
 107 http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]).
 108
 109
 110 Lists
 111 ~~~~~
 112
 113 Numbered Lists
 114 ^^^^^^^^^^^^^^
 115
 116 Numbered lists should be created using the implicit numbering format:
 117
 118 -----
 119 . First level
 120 .. Second level
 121 . First level again
 122 -----
 123
 124 . First level
 125 .. Second level
 126 . First level again
 127
 128
 129 Bulleted Lists
 130 ^^^^^^^^^^^^^^
 131
 132 Bulleted lists should be created using the '*' symbol:
 133
 134 -----
 135 * First level
 136 ** Second level
 137 * First level again
 138 -----
 139
 140 * First level
 141 ** Second level
 142 * First level again
 143
 144
 145 If you need to have other elements on the same level than a list element you
 146 can do this with the '+' symbol:
 147
 148 ----
 149 . First level
 150 .. Second level
 151 +
 152 Anothe Sentence (or Block) on the continued second level.
 153 . First level again
 154 ----
 155
 156 . First level
 157 .. Second level
 158 +
 159 Anothe Sentence (or Block) on the continued second level.
 160
 161 . First level again
 162
 163 Labeled Lists
 164 ^^^^^^^^^^^^^
 165
 166 Labeled lists should be used to make lists of key-value style text
 167 more readable, such as command line parameters or configuration options:
 168
 169 .Regular labeled lists
 170 -----
 171 First Label Text::
 172
 173 Element text paragraph
 174
 175 Second Label Text::
 176
 177 Another element text paragraph.
 178 -----
 179
 180 First Label Text::
 181
 182 Element text paragraph
 183
 184 Second Label Text::
 185
 186 Another element text paragraph.
 187
 188 .Horizontal labeled lists
 189 -----
 190 [horizontal]
 191 First Label Text:: Element text paragraph
 192
 193 Second Label Text:: Another element text paragraph.
 194 -----
 195
 196 creates
 197
 198 [horizontal]
 199 First Label Text:: Element text paragraph
 200
 201 Second Label Text:: Another element text paragraph.
 202
 203 The FAQ section uses a special questions and answers style for
 204 labeled lists.
 205
 206
 207 Text and Block Styles
 208 ~~~~~~~~~~~~~~~~~~~~~
 209
 210 'asciidoc' offers a wide range of default text styles:
 211
 212 * 'Emphasized text': created using \'text', used for emphasizing words
 213 and phrases
 214 * `Monospaced text`: created using \`text`, used for command / program
 215 names, file paths, in-line commands, option names and values
 216 * *Strong text*: created using \*text*, used for emphasizing concepts
 217 or names when first introduced in a section.
 218
 219 There are also different built-in block styles that are used in
 220 our documentation:
 221
 222 Complete paragraphs can be included literally by prepending each
 223 of their lines with whitespace. Use this for formatting complete
 224 commands on their own line, such as:
 225
 226  pct set ID -option value
 227
 228 ----
 229 By surrounding a paragraph with lines containing at least four '-'
 230 characters, its content is formatted as listing.
 231
 232 Use this for formatting file contents or command output.
 233 ----
 234
 235 Specially highlighted 'notes', 'warnings' and 'important' information
 236 can be created by starting a paragraph with `NOTE:`, `WARNING:` or
 237 `IMPORTANT:`:
 238
 239 NOTE: this is a note
 240
 241 WARNING: this is warning
 242
 243 IMPORTANT: this is important information
 244
 245 For each of these blocks (including lists and paragraphs), a block header
 246 can be defined by prepending the block with a `.' character and the header
 247 text:
 248
 249 -----
 250 .Title of List
 251 * First element
 252 * Second element
 253 * Third element
 254 -----
 255
 256 .Title of List
 257 * First element
 258 * Second element
 259 * Third element
 260
 261 For example, block headers can be used to add file names/paths to file
 262 content listings.
 263
 264
 265 Online Help
 266 -----------
 267 Each {pve} installation contains the full documentation in HTML format,
 268 which is then used as the target of various help buttons in the GUI.
 269
 270 If after adding a specific entry in the documentation you want to
 271 create a help button pointing to that, you need to do the
 272 following:
 273
 274 * add a string id in double square brackets before your
 275 documentation entry,  like `[[qm_general_settings]]`
 276 * rebuild the `asciidoc-pve` script and the HTML chapter file containing
 277 your entry
 278 * add a property `onlineHelp` in the ExtJS panel you want to document,
 279 using the above string, like `onlineHelp: qm_general_settings`
 280 This panel has to be a child class of PVE.panel.InputPanel
 281
 282 On calling `make install` the asciidoc-pve script will populate
 283 a JS object associating the string id and a link to the
 284 local HTML documentation, and the help button of your input panel
 285 will point to this link.
 286
 287
 288 Screenshots
 289 -----------
 290
 291 [thumbnail="screenshot/gui-datacenter-search.png"]
 292
 293 First, it should be noted that we can display screenshots on 'html'
 294 and 'wiki' pages, and we can include them in printed documentation. But
 295 it is not possible to render them inside manual pages. So screenshot
 296 inside manual pages should be optional, i.e. the text should not
 297 depend on the visibility of the screenshot. You can include a
 298 screenshot by setting the 'thumbnail' attribute on a paragraph:
 299
 300 ----
 301 [thumbnail="screenshot/gui-datacenter-search.png"]
 302 First, it should be noted ...
 303 ----
 304
 305 The corresponding file need to reside inside folder
 306 `images/screenshot`, and should be in `.png` image format. We include
 307 the screenshots in printed documentation, and 'pdftex' uses the
 308 density (DPI) specified inside the file. So all screenshots should use
 309 the same density. We currently require the density set to 146 DPI, so
 310 that we can display a 1024 pixels wide image. You should not include
 311 larger screenshots (although it is possible).
 312
 313 You can use the `./png-cleanup.pl` script to set the correct
 314 density. Simply use the following command to import a screenshot
 315 image:
 316
 317 ----
 318 # ./png-cleanup.pl screenshot.png images/screenshot/screenshot.png
 319 ----
 320
 321 TIP: You can use `identify -verbose screenshot.png` command to show
 322 all image attributes (from debian package 'imagemagick')
 323
 324 .Default Screenshot Layout
 325
 326 [thumbnail="screenshot/gui-datacenter-search.png"]
 327
 328 We normally display screenshots as small thumbnail on the right side
 329 of a paragraph. On printed documentation, we render the full sized
 330 graphic just before the paragraph, or between the title and the text
 331 if the paragraph has a title. It is usually a good idea to add a title
 332 to paragraph with screenshots.
 333
 334 [thumbnail="screenshot/gui-datacenter-search.png", float="left"]
 335
 336 If you need to render many screenshots, it is possible to place them
 337 on the left side, so you can alternate the thumbnail position using the
 338 `float` attribute:
 339
 340 ----
 341 [thumbnail="screenshot/gui-datacenter-search.png", float="left"]
 342 If you need to render many screenshots ...
 343 ----
 344
 345 Please avoid to many consecutive screenshots to avoid rendering
 346 problems. Also verify the printed documentation to see if large
 347 screenshots create layout problems.
 348
 349
 350 Copyright
 351 ---------
 352
 353 Copyright (C) 2016-2017 Proxmox Server Solutions Gmbh
 354
 355 Permission is granted to copy, distribute and/or modify this document
 356 under the terms of the GNU Free Documentation License, Version 1.3 or
 357 any later version published by the Free Software Foundation; with no
 358 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
 359 copy of the license is included in the link:LICENSE[LICENSE] file.