X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=README.adoc;h=aa795c082ec3d75aa43759b91960c7b646b29e72;hp=dbd04106402ccd8e2868dadc0c1f7b4b81b7659b;hb=94958b8b9230d5b9b5e2e70c481f115b18a5fa0b;hpb=578a3111a34e7f1bec5bdccec7819619d9ebb83c diff --git a/README.adoc b/README.adoc index dbd0410..aa795c0 100644 --- a/README.adoc +++ b/README.adoc @@ -1,18 +1,70 @@ Proxmox VE Documentation ======================== -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 +{website}[{pve}], 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'). +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 ---------------------------------- @@ -24,14 +76,285 @@ definition of the {pve} API. I added those generated files 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 than a list element you +can do this with the '+' symbol: + +---- +. First level +.. Second level ++ +Anothe Sentence (or Block) on the continued second level. +. First level again +---- + +. First level +.. Second level ++ +Anothe 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) Proxmox Server Solutions Gmbh +Copyright (C) 2016-2017 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.