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 pve-doc-generator.mk
  22  make index
  23
  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
  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
  40 those Debian packages using:
  41
  42  make deb
  43
  44
  45 Common Macro definition in link:asciidoc/asciidoc-pve.conf[]
  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
  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
  63 than once.
  64
  65 WARNING: When asciidoc encounters a misspelled macro name, it will
  66 silently drop the containing line!
  67
  68
  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.
  78
  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
 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
 104 Section titles should always be preceded by two empty lines. Each word
 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
 146 If you need to have other elements on the same level than a list element you
 147 can do this with the '+' symbol:
 148
 149 ----
 150 . First level
 151 .. Second level
 152 +
 153 Anothe Sentence (or Block) on the continued second level.
 154 . First level again
 155 ----
 156
 157 . First level
 158 .. Second level
 159 +
 160 Anothe Sentence (or Block) on the continued second level.
 161
 162 . First level again
 163
 164 Labeled Lists
 165 ^^^^^^^^^^^^^
 166
 167 Labeled lists should be used to make lists of key-value style text
 168 more readable, such as command line parameters or configuration options:
 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
 216 names, file paths, in-line commands, option names and values
 217 * *Strong text*: created using \*text*, used for emphasizing concepts
 218 or names when first introduced in a section.
 219
 220 There are also different built-in block styles that are used in
 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
 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
 289 Screenshots
 290 -----------
 291
 292 [thumbnail="screenshot/gui-datacenter-search.png"]
 293
 294 First, it should be noted that we can display screenshots on 'html'
 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
 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 ----
 302 [thumbnail="screenshot/gui-datacenter-search.png"]
 303 First, it should be noted ...
 304 ----
 305
 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
 325 .Default Screenshot Layout
 326
 327 [thumbnail="screenshot/gui-datacenter-search.png"]
 328
 329 We normally display screenshots as small thumbnail on the right side
 330 of a paragraph. On printed documentation, we render the full sized
 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
 335 [thumbnail="screenshot/gui-datacenter-search.png", float="left"]
 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 ----
 342 [thumbnail="screenshot/gui-datacenter-search.png", float="left"]
 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.
 349
 350
 351 Copyright
 352 ---------
 353
 354 Copyright (C) 2016-2017 Proxmox Server Solutions Gmbh
 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
 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.