mirror of
git://git.proxmox.com/git/pve-docs.git
synced 2025-01-06 13:17:48 +03:00
361 lines
10 KiB
Plaintext
361 lines
10 KiB
Plaintext
Proxmox VE Documentation
|
|
========================
|
|
|
|
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 pve-doc-generator.mk
|
|
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:asciidoc/asciidoc-pve.conf[]
|
|
------------------------------------------------------------
|
|
|
|
'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!
|
|
|
|
|
|
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): ++++++++++++++++++++++
|
|
|
|
NOTE: Level 4 headings are currently not working for `manpage` outputs, you may
|
|
want to use `.SECTION' instead, which results in the same rendering, and this
|
|
level of Heading isn't displayed in any Index/TOC anyway.
|
|
|
|
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
|
|
|
|
|
|
If you need to have other elements on the same level as a list element you
|
|
can do this with the '+' symbol:
|
|
|
|
----
|
|
. First level
|
|
.. Second level
|
|
+
|
|
Another Sentence (or Block) on the continued second level.
|
|
. First level again
|
|
----
|
|
|
|
. First level
|
|
.. Second level
|
|
+
|
|
Another Sentence (or Block) on the continued 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.
|
|
|
|
|
|
Online Help
|
|
-----------
|
|
Each {pve} installation contains the full documentation in HTML format,
|
|
which is then used as the target of various help buttons in the GUI.
|
|
|
|
If after adding a specific entry in the documentation you want to
|
|
create a help button pointing to that, you need to do the
|
|
following:
|
|
|
|
* add a string id in double square brackets before your
|
|
documentation entry, like `[[qm_general_settings]]`
|
|
* rebuild the `asciidoc-pve` script and the HTML chapter file containing
|
|
your entry
|
|
* add a property `onlineHelp` in the ExtJS panel you want to document,
|
|
using the above string, like `onlineHelp: qm_general_settings`
|
|
This panel has to be a child class of PVE.panel.InputPanel
|
|
|
|
On calling `make install` the asciidoc-pve script will populate
|
|
a JS object associating the string id and a link to the
|
|
local HTML documentation, and the help button of your input panel
|
|
will point to this link.
|
|
|
|
|
|
Screenshots
|
|
-----------
|
|
|
|
[thumbnail="screenshot/gui-datacenter-search.png"]
|
|
|
|
First, it should be noted that we can display screenshots on 'html'
|
|
and 'wiki' pages, and we can include them in printed documentation. But
|
|
it is not possible to render them inside manual pages. So screenshot
|
|
inside manual pages should be optional, i.e. the text should not
|
|
depend on the visibility of the screenshot. You can include a
|
|
screenshot by setting the 'thumbnail' attribute on a paragraph:
|
|
|
|
----
|
|
[thumbnail="screenshot/gui-datacenter-search.png"]
|
|
First, it should be noted ...
|
|
----
|
|
|
|
The corresponding file need to reside inside folder
|
|
`images/screenshot`, and should be in `.png` image format. We include
|
|
the screenshots in printed documentation, and 'pdftex' uses the
|
|
density (DPI) specified inside the file. So all screenshots should use
|
|
the same density. We currently require the density set to 146 DPI, so
|
|
that we can display a 1024 pixels wide image. You should not include
|
|
larger screenshots (although it is possible).
|
|
|
|
You can use the `./png-cleanup.pl` script to set the correct
|
|
density. Simply use the following command to import a screenshot
|
|
image:
|
|
|
|
----
|
|
# ./png-cleanup.pl screenshot.png images/screenshot/screenshot.png
|
|
----
|
|
|
|
TIP: You can use `identify -verbose screenshot.png` command to show
|
|
all image attributes (from debian package 'imagemagick')
|
|
|
|
.Default Screenshot Layout
|
|
|
|
[thumbnail="screenshot/gui-datacenter-search.png"]
|
|
|
|
We normally display screenshots as small thumbnail on the right side
|
|
of a paragraph. On printed documentation, we render the full sized
|
|
graphic just before the paragraph, or between the title and the text
|
|
if the paragraph has a title. It is usually a good idea to add a title
|
|
to paragraph with screenshots.
|
|
|
|
[thumbnail="screenshot/gui-datacenter-search.png", float="left"]
|
|
|
|
If you need to render many screenshots, it is possible to place them
|
|
on the left side, so you can alternate the thumbnail position using the
|
|
`float` attribute:
|
|
|
|
----
|
|
[thumbnail="screenshot/gui-datacenter-search.png", float="left"]
|
|
If you need to render many screenshots ...
|
|
----
|
|
|
|
Please avoid to many consecutive screenshots to avoid rendering
|
|
problems. Also verify the printed documentation to see if large
|
|
screenshots create layout problems.
|
|
|
|
|
|
Copyright
|
|
---------
|
|
|
|
Copyright (C) 2016-2021 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.
|