Proxmox VE Documentation
========================
+include::attributes.txt[]
-What is this?
--------------
-
-This is an experimental project, trying to generate high quality
-documentation for http://www.proxmox.com[Proxmox VE]. We choose to use
+We try to generate high quality documentation for
+http://www.proxmox.com[Proxmox VE], and choose to use
http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
-One idea is to generate high quality manual pages, and assemble them
-into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
+The basic idea is to generate high quality manual pages, and assemble
+them into a complete book, called link:pve-admin-guide.adoc[Proxmox VE
Administration Guide]. So we have one source, and generate several
documents from that. It is also possible to generate printable PDF
files, or ebook formats ('.ebup').
+When possible, we provide scripts to extract API definitions,
+configuration or command line options from the source code.
+
+To simplify the documentation task, we keep all Documentation within
+this repository. It is possible to generate the docs without installing
+any additional Proxmox packages with:
+
+ make index
+
+To update the auto-generate API definitions use:
+
+ make update
+
+NOTE: you need a fully installed development environment for that.
+
+
+Debian Packages
+---------------
+
+We generate a development package called 'pve-doc-generator', which is
+used by other Proxmox VE package to generate manual pages at package
+build time.
+
+Another package called 'pve-docs' is used to publish generated
+'.html' and '.pdf' files on our web servers. You can generate
+those Debian packages using:
+
+ make deb
+
+
+Common Macro definition in link:attributes.txt[]
+------------------------------------------------
+
+'asciidoc' allows us to define common macros, which can then be
+referred to using `{macro}`. We try to use this mechanism to improve
+consistency. For example, we defined a macro called `pve`, which
+expands to "Proxmox VE". The plan is to add more such definitions for
+terms which are used more than once.
+
+Autogenerated CLI Command Synopsis
+----------------------------------
+
+We generate the command line synopsis for all manual pages
+automatically. We can do that, because we have a full declarative
+definition of the {pve} API. I added those generated files
+('*-synopsis.adoc') to the git repository, so that it is possible to
+build the documentation without having a fully installed {pve}
+development environment.
+
+Style Guide
+-----------
+
+'asciidoc' uses a fairly simple markup syntax for formatting content.
+The following basic principles should be followed throughout our
+documentation.
+
+
+Sections
+~~~~~~~~
+
+Sections are formatted using `two-line titles', by adding a line of
+the appropriate characters and of the same length as the section title
+below the title text:
+
+ Level 0 (top level): ======================
+ Level 1: ----------------------
+ Level 2: ~~~~~~~~~~~~~~~~~~~~~~
+ Level 3: ^^^^^^^^^^^^^^^^^^^^^^
+ Level 4 (bottom level): ++++++++++++++++++++++
+
+Section titles should always be preceded by two empty lines. Each word
+in a title should be capitalized except for ``articles, coordinating
+conjunctions, prepositions, and the word to in infinitives unless they
+appear as the first or last word of a title'' (see
+http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]).
+
+
+Lists
+~~~~~
+
+Numbered Lists
+^^^^^^^^^^^^^^
+
+Numbered lists should be created using the implicit numbering format:
+
+-----
+. First level
+.. Second level
+. First level again
+-----
+
+. First level
+.. Second level
+. First level again
+
+
+Bulleted Lists
+^^^^^^^^^^^^^^
+
+Bulleted lists should be created using the '*' symbol:
+
+-----
+* First level
+** Second level
+* First level again
+-----
+
+* First level
+** Second level
+* First level again
+
+
+Labeled Lists
+^^^^^^^^^^^^^
+
+Labeled lists should be used to make lists of key-value style text
+more readable, such as command line parameters or configuration options:
+
+.Regular labeled lists
+-----
+First Label Text::
+
+Element text paragraph
+
+Second Label Text::
+
+Another element text paragraph.
+-----
+
+First Label Text::
+
+Element text paragraph
+
+Second Label Text::
+
+Another element text paragraph.
+
+.Horizontal labeled lists
+-----
+[horizontal]
+First Label Text:: Element text paragraph
+
+Second Label Text:: Another element text paragraph.
+-----
+
+creates
+
+[horizontal]
+First Label Text:: Element text paragraph
+
+Second Label Text:: Another element text paragraph.
+
+The FAQ section uses a special questions and answers style for
+labeled lists.
+
+
+Text and Block Styles
+~~~~~~~~~~~~~~~~~~~~~
+
+'asciidoc' offers a wide range of default text styles:
+
+* 'Emphasized text': created using \'text', used for emphasizing words
+and phrases
+* `Monospaced text`: created using \`text`, used for command / program
+names, file paths, inline commands, option names and values
+* *Strong text*: created using \*text*, used for emphasizing concepts
+or names when first introduced in a section.
+
+There are also different builtin block styles that are used in
+our documentation:
+
+Complete paragraphs can be included literally by prepending each
+of their lines with whitespace. Use this for formatting complete
+commands on their own line, such as:
+
+ pct set ID -option value
+
+----
+By surrounding a paragraph with lines containing at least four '-'
+characters, its content is formatted as listing.
+
+Use this for formatting file contents or command output.
+----
+
+Specially highlighted 'notes', 'warnings' and 'important' information
+can be created by starting a paragraph with `NOTE:`, `WARNING:` or
+`IMPORTANT:`:
+
+NOTE: this is a note
+
+WARNING: this is warning
+
+IMPORTANT: this is important information
+
+For each of these blocks (including lists and paragraphs), a block header
+can be defined by prepending the block with a `.' character and the header
+text:
+
+-----
+.Title of List
+* First element
+* Second element
+* Third element
+-----
+
+.Title of List
+* First element
+* Second element
+* Third element
+
+For example, block headers can be used to add file names/paths to file
+content listings.
+
Copyright
---------
-Copyright (C) Proxmox Server Solutions Gmbh
+Copyright (C) 2016 Proxmox Server Solutions Gmbh
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
-copy of the license is included in the section entitled "GNU Free
-Documentation License".
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the link:LICENSE[LICENSE] file.
projects / pve-docs.git / blobdiff