You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.adoc 10KB

  1. Proxmox VE Documentation
  2. ========================
  3. We try to generate high quality documentation for
  4. {website}[{pve}], and choose to use
  5.[AsciiDoc] as base format.
  6. The basic idea is to generate high quality manual pages, and assemble
  7. them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
  8. Administration Guide]. So we have one source, and generate several
  9. documents from that. It is also possible to generate printable PDF
  10. files, or ebook formats ('.epub').
  11. When possible, we provide scripts to extract API definitions,
  12. configuration or command line options from the source code.
  13. To simplify the documentation task, we keep all Documentation within
  14. this repository. It is possible to generate the docs without installing
  15. any additional Proxmox packages with:
  16. make
  17. make index
  18. To update the auto-generate API definitions use:
  19. make update
  20. NOTE: you need a fully installed development environment for that.
  21. Debian Packages
  22. ---------------
  23. We generate a development package called 'pve-doc-generator', which is
  24. used by other Proxmox VE package to generate manual pages at package
  25. build time.
  26. Another package called 'pve-docs' is used to publish generated
  27. '.html' and '.pdf' files on our web servers. You can generate
  28. those Debian packages using:
  29. make deb
  30. Common Macro definition in link:asciidoc/asciidoc-pve.conf[]
  31. ------------------------------------------------------------
  32. 'asciidoc' allows us to define common macros, which can then be
  33. referred to using `{macro}`. We try to use this mechanism to improve
  34. consistency. For example, we defined a macro called `pve`, which
  35. expands to "Proxmox VE".
  36. For URLs which are used more than once, two macros should be defined:
  37. * `{name-url}`, which just contains the http(s) URL
  38. * `{name}`, which contains the complete link including the canonical
  39. description
  40. For example, the macro `{forum-url}` expands to {forum-url}, and the macro
  41. `{forum}` expands to {forum}.
  42. The plan is to add more such definitions for terms which are used more
  43. than once.
  44. WARNING: When asciidoc encounters a misspelled macro name, it will
  45. silently drop the containing line!
  46. Autogenerated CLI Command Synopsis
  47. ----------------------------------
  48. We generate the command line synopsis for all manual pages
  49. automatically. We can do that, because we have a full declarative
  50. definition of the {pve} API. I added those generated files
  51. ('*-synopsis.adoc') to the git repository, so that it is possible to
  52. build the documentation without having a fully installed {pve}
  53. development environment.
  54. Style Guide
  55. -----------
  56. 'asciidoc' uses a fairly simple markup syntax for formatting content.
  57. The following basic principles should be followed throughout our
  58. documentation.
  59. Sections
  60. ~~~~~~~~
  61. Sections are formatted using `two-line titles', by adding a line of
  62. the appropriate characters and of the same length as the section title
  63. below the title text:
  64. Level 0 (top level): ======================
  65. Level 1: ----------------------
  66. Level 2: ~~~~~~~~~~~~~~~~~~~~~~
  67. Level 3: ^^^^^^^^^^^^^^^^^^^^^^
  68. Level 4 (bottom level): ++++++++++++++++++++++
  69. NOTE: Level 4 headings are currently not working for `manpage` outputs, you may
  70. want to use `.SECTION' instead, which results in the same rendering, and this
  71. level of Heading isn't displayed in any Index/TOC anyway.
  72. Section titles should always be preceded by two empty lines. Each word
  73. in a title should be capitalized except for ``articles, coordinating
  74. conjunctions, prepositions, and the word to in infinitives unless they
  75. appear as the first or last word of a title'' (see
  76.[Mayfield Electronic Handbook of Technical & Scientific Writing]).
  77. Lists
  78. ~~~~~
  79. Numbered Lists
  80. ^^^^^^^^^^^^^^
  81. Numbered lists should be created using the implicit numbering format:
  82. -----
  83. . First level
  84. .. Second level
  85. . First level again
  86. -----
  87. . First level
  88. .. Second level
  89. . First level again
  90. Bulleted Lists
  91. ^^^^^^^^^^^^^^
  92. Bulleted lists should be created using the '*' symbol:
  93. -----
  94. * First level
  95. ** Second level
  96. * First level again
  97. -----
  98. * First level
  99. ** Second level
  100. * First level again
  101. If you need to have other elements on the same level than a list element you
  102. can do this with the '+' symbol:
  103. ----
  104. . First level
  105. .. Second level
  106. +
  107. Anothe Sentence (or Block) on the continued second level.
  108. . First level again
  109. ----
  110. . First level
  111. .. Second level
  112. +
  113. Anothe Sentence (or Block) on the continued second level.
  114. . First level again
  115. Labeled Lists
  116. ^^^^^^^^^^^^^
  117. Labeled lists should be used to make lists of key-value style text
  118. more readable, such as command line parameters or configuration options:
  119. .Regular labeled lists
  120. -----
  121. First Label Text::
  122. Element text paragraph
  123. Second Label Text::
  124. Another element text paragraph.
  125. -----
  126. First Label Text::
  127. Element text paragraph
  128. Second Label Text::
  129. Another element text paragraph.
  130. .Horizontal labeled lists
  131. -----
  132. [horizontal]
  133. First Label Text:: Element text paragraph
  134. Second Label Text:: Another element text paragraph.
  135. -----
  136. creates
  137. [horizontal]
  138. First Label Text:: Element text paragraph
  139. Second Label Text:: Another element text paragraph.
  140. The FAQ section uses a special questions and answers style for
  141. labeled lists.
  142. Text and Block Styles
  143. ~~~~~~~~~~~~~~~~~~~~~
  144. 'asciidoc' offers a wide range of default text styles:
  145. * 'Emphasized text': created using \'text', used for emphasizing words
  146. and phrases
  147. * `Monospaced text`: created using \`text`, used for command / program
  148. names, file paths, in-line commands, option names and values
  149. * *Strong text*: created using \*text*, used for emphasizing concepts
  150. or names when first introduced in a section.
  151. There are also different built-in block styles that are used in
  152. our documentation:
  153. Complete paragraphs can be included literally by prepending each
  154. of their lines with whitespace. Use this for formatting complete
  155. commands on their own line, such as:
  156. pct set ID -option value
  157. ----
  158. By surrounding a paragraph with lines containing at least four '-'
  159. characters, its content is formatted as listing.
  160. Use this for formatting file contents or command output.
  161. ----
  162. Specially highlighted 'notes', 'warnings' and 'important' information
  163. can be created by starting a paragraph with `NOTE:`, `WARNING:` or
  164. `IMPORTANT:`:
  165. NOTE: this is a note
  166. WARNING: this is warning
  167. IMPORTANT: this is important information
  168. For each of these blocks (including lists and paragraphs), a block header
  169. can be defined by prepending the block with a `.' character and the header
  170. text:
  171. -----
  172. .Title of List
  173. * First element
  174. * Second element
  175. * Third element
  176. -----
  177. .Title of List
  178. * First element
  179. * Second element
  180. * Third element
  181. For example, block headers can be used to add file names/paths to file
  182. content listings.
  183. Online Help
  184. -----------
  185. Each {pve} installation contains the full documentation in HTML format,
  186. which is then used as the target of various help buttons in the GUI.
  187. If after adding a specific entry in the documentation you want to
  188. create a help button pointing to that, you need to do the
  189. following:
  190. * add a string id in double square brackets before your
  191. documentation entry, like `[[qm_general_settings]]`
  192. * rebuild the `asciidoc-pve` script and the HTML chapter file containing
  193. your entry
  194. * add a property `onlineHelp` in the ExtJS panel you want to document,
  195. using the above string, like `onlineHelp: qm_general_settings`
  196. This panel has to be a child class of PVE.panel.InputPanel
  197. On calling `make install` the asciidoc-pve script will populate
  198. a JS object associating the string id and a link to the
  199. local HTML documentation, and the help button of your input panel
  200. will point to this link.
  201. Screenshots
  202. -----------
  203. [thumbnail="screenshot/gui-datacenter-search.png"]
  204. First, it should be noted that we can display screenshots on 'html'
  205. and 'wiki' pages, and we can include them in printed documentation. But
  206. it is not possible to render them inside manual pages. So screenshot
  207. inside manual pages should be optional, i.e. the text should not
  208. depend on the visibility of the screenshot. You can include a
  209. screenshot by setting the 'thumbnail' attribute on a paragraph:
  210. ----
  211. [thumbnail="screenshot/gui-datacenter-search.png"]
  212. First, it should be noted ...
  213. ----
  214. The corresponding file need to reside inside folder
  215. `images/screenshot`, and should be in `.png` image format. We include
  216. the screenshots in printed documentation, and 'pdftex' uses the
  217. density (DPI) specified inside the file. So all screenshots should use
  218. the same density. We currently require the density set to 146 DPI, so
  219. that we can display a 1024 pixels wide image. You should not include
  220. larger screenshots (although it is possible).
  221. You can use the `./` script to set the correct
  222. density. Simply use the following command to import a screenshot
  223. image:
  224. ----
  225. # ./ screenshot.png images/screenshot/screenshot.png
  226. ----
  227. TIP: You can use `identify -verbose screenshot.png` command to show
  228. all image attributes (from debian package 'imagemagick')
  229. .Default Screenshot Layout
  230. [thumbnail="screenshot/gui-datacenter-search.png"]
  231. We normally display screenshots as small thumbnail on the right side
  232. of a paragraph. On printed documentation, we render the full sized
  233. graphic just before the paragraph, or between the title and the text
  234. if the paragraph has a title. It is usually a good idea to add a title
  235. to paragraph with screenshots.
  236. [thumbnail="screenshot/gui-datacenter-search.png", float="left"]
  237. If you need to render many screenshots, it is possible to place them
  238. on the left side, so you can alternate the thumbnail position using the
  239. `float` attribute:
  240. ----
  241. [thumbnail="screenshot/gui-datacenter-search.png", float="left"]
  242. If you need to render many screenshots ...
  243. ----
  244. Please avoid to many consecutive screenshots to avoid rendering
  245. problems. Also verify the printed documentation to see if large
  246. screenshots create layout problems.
  247. Copyright
  248. ---------
  249. Copyright (C) 2016-2019 Proxmox Server Solutions Gmbh
  250. Permission is granted to copy, distribute and/or modify this document
  251. under the terms of the GNU Free Documentation License, Version 1.3 or
  252. any later version published by the Free Software Foundation; with no
  253. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  254. copy of the license is included in the link:LICENSE[LICENSE] file.