mirror of
https://git.proxmox.com/git/pve-docs
synced 2025-10-31 22:52:15 +00:00
255 lines
6.7 KiB
Plaintext
255 lines
6.7 KiB
Plaintext
Proxmox VE Documentation
|
|
========================
|
|
include::attributes.txt[]
|
|
|
|
We try to generate high quality documentation for
|
|
{website}[{pve}], and choose to use
|
|
http://www.methods.co.nz/asciidoc/[AsciiDoc] as base format.
|
|
|
|
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 ('.epub').
|
|
|
|
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".
|
|
|
|
For URLs which are used more than once, two macros should be defined:
|
|
|
|
* `{name-url}`, which just contains the http(s) URL
|
|
* `{name}`, which contains the complete link including the canonical
|
|
description
|
|
|
|
For example, the macro `{forum-url}` expands to {forum-url}, and the macro
|
|
`{forum}` expands to {forum}.
|
|
|
|
The plan is to add more such definitions for terms which are used more than once.
|
|
|
|
WARNING: When asciidoc encounters a misspelled macro name, it will silently drop
|
|
the containing line!
|
|
|
|
WARNING: Never use macros in document titles or the ``NAME'' section of man pages,
|
|
as these get parsed before the `attributes.txt` file gets included.
|
|
|
|
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, in-line 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 built-in 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) 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 link:LICENSE[LICENSE] file.
|