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 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
 243 Copyright
 244 ---------
 245
 246 Copyright (C) 2016 Proxmox Server Solutions Gmbh
 247
 248 Permission is granted to copy, distribute and/or modify this document
 249 under the terms of the GNU Free Documentation License, Version 1.3 or
 250 any later version published by the Free Software Foundation; with no
 251 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
 252 copy of the license is included in the link:LICENSE[LICENSE] file.