README.adoc

   1 Proxmox VE Documentation
   2 ========================
   3 include::attributes.txt[]
   4
   5 We try to generate high quality documentation for
   6 http://www.proxmox.com[Proxmox VE], and choose to use
   7 http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
   8
   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
  11 Administration Guide].  So we have one source, and generate several
  12 documents from that. It is also possible to generate printable PDF
  13 files, or ebook formats ('.epub').
  14
  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
  19 this repository. It is possible to generate the docs without installing
  20 any additional Proxmox packages with:
  21
  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: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
  51 expands to "Proxmox VE". The plan is to add more such definitions for
  52 terms which are used more than once.
  53
  54 Autogenerated CLI Command Synopsis
  55 ----------------------------------
  56
  57 We generate the command line synopsis for all manual pages
  58 automatically. We can do that, because we have a full declarative
  59 definition of the {pve} API. I added those generated files
  60 ('*-synopsis.adoc') to the git repository, so that it is possible to
  61 build the documentation without having a fully installed {pve}
  62 development environment.
  63
  64 Style Guide
  65 -----------
  66
  67 'asciidoc' uses a fairly simple markup syntax for formatting content.
  68 The following basic principles should be followed throughout our
  69 documentation.
  70
  71
  72 Sections
  73 ~~~~~~~~
  74
  75 Sections are formatted using `two-line titles', by adding a line of
  76 the appropriate characters and of the same length as the section title
  77 below the title text:
  78
  79  Level 0 (top level):     ======================
  80  Level 1:                 ----------------------
  81  Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
  82  Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
  83  Level 4 (bottom level):  ++++++++++++++++++++++
  84
  85 Section titles should always be preceded by two empty lines. Each word
  86 in a title should be capitalized except for ``articles, coordinating
  87 conjunctions, prepositions, and the word to in infinitives unless they
  88 appear as the first or last word of a title'' (see
  89 http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]).
  90
  91
  92 Lists
  93 ~~~~~
  94
  95 Numbered Lists
  96 ^^^^^^^^^^^^^^
  97
  98 Numbered lists should be created using the implicit numbering format:
  99
 100 -----
 101 . First level
 102 .. Second level
 103 . First level again
 104 -----
 105
 106 . First level
 107 .. Second level
 108 . First level again
 109
 110
 111 Bulleted Lists
 112 ^^^^^^^^^^^^^^
 113
 114 Bulleted lists should be created using the '*' symbol:
 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 Labeled Lists
 128 ^^^^^^^^^^^^^
 129
 130 Labeled lists should be used to make lists of key-value style text
 131 more readable, such as command line parameters or configuration options:
 132
 133 .Regular labeled lists
 134 -----
 135 First Label Text::
 136
 137 Element text paragraph
 138
 139 Second Label Text::
 140
 141 Another element text paragraph.
 142 -----
 143
 144 First Label Text::
 145
 146 Element text paragraph
 147
 148 Second Label Text::
 149
 150 Another element text paragraph.
 151
 152 .Horizontal labeled lists
 153 -----
 154 [horizontal]
 155 First Label Text:: Element text paragraph
 156
 157 Second Label Text:: Another element text paragraph.
 158 -----
 159
 160 creates
 161
 162 [horizontal]
 163 First Label Text:: Element text paragraph
 164
 165 Second Label Text:: Another element text paragraph.
 166
 167 The FAQ section uses a special questions and answers style for
 168 labeled lists.
 169
 170
 171 Text and Block Styles
 172 ~~~~~~~~~~~~~~~~~~~~~
 173
 174 'asciidoc' offers a wide range of default text styles:
 175
 176 * 'Emphasized text': created using \'text', used for emphasizing words
 177 and phrases
 178 * `Monospaced text`: created using \`text`, used for command / program
 179 names, file paths, in-line commands, option names and values
 180 * *Strong text*: created using \*text*, used for emphasizing concepts
 181 or names when first introduced in a section.
 182
 183 There are also different built-in block styles that are used in
 184 our documentation:
 185
 186 Complete paragraphs can be included literally by prepending each
 187 of their lines with whitespace. Use this for formatting complete
 188 commands on their own line, such as:
 189
 190  pct set ID -option value
 191
 192 ----
 193 By surrounding a paragraph with lines containing at least four '-'
 194 characters, its content is formatted as listing.
 195
 196 Use this for formatting file contents or command output.
 197 ----
 198
 199 Specially highlighted 'notes', 'warnings' and 'important' information
 200 can be created by starting a paragraph with `NOTE:`, `WARNING:` or
 201 `IMPORTANT:`:
 202
 203 NOTE: this is a note
 204
 205 WARNING: this is warning
 206
 207 IMPORTANT: this is important information
 208
 209 For each of these blocks (including lists and paragraphs), a block header
 210 can be defined by prepending the block with a `.' character and the header
 211 text:
 212
 213 -----
 214 .Title of List
 215 * First element
 216 * Second element
 217 * Third element
 218 -----
 219
 220 .Title of List
 221 * First element
 222 * Second element
 223 * Third element
 224
 225 For example, block headers can be used to add file names/paths to file
 226 content listings.
 227
 228
 229 Copyright
 230 ---------
 231
 232 Copyright (C) 2016 Proxmox Server Solutions Gmbh
 233
 234 Permission is granted to copy, distribute and/or modify this document
 235 under the terms of the GNU Free Documentation License, Version 1.3 or
 236 any later version published by the Free Software Foundation; with no
 237 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
 238 copy of the license is included in the link:LICENSE[LICENSE] file.