我们努力为{website}[{pve}]生成高质量文档，并选择使用http://www.methods.co.nz/asciidoc/[AsciiDoc]作为基础格式。

基本思想是生成高质量的手册页面，并将它们组装成一本完整的书籍，称为链接：pve-admin-guide.adoc[Proxmox VE 管理指南]。因此我们有了一个源，可以从中生成多个文档。也可以生成可打印的PDF文件，或者电子书格式（.epub）。

当可能时，我们提供脚本来从源代码中提取API定义、配置或命令行选项。

为了简化文档任务，我们将所有文档保存在此仓库中。可以在不安装任何额外的Proxmox包的情况下生成文档：

make pve-doc-generator.mk make index

要更新自动生成的API定义，请使用：

make update

Note
 你需要一个完整安装的开发环境来做那件事。

Debian 软件包

我们生成了一个名为’pve-doc-generator’的开发包，其他Proxmox VE包在打包构建时使用它来生成手册页面。

另一个名为 pve-docs 的包用于在我们的网服务器上发布生成的 .html 和 .pdf 文件。您可以使用以下命令生成那些Debian包：

创建 deb 包

常见宏定义链接：asciidoc/asciidoc-pve.conf[]

'asciidoc’允许我们定义通用宏，在此之后可以通过`{macro}`来引用这些宏。我们尝试使用这种机制来提高一致性。例如，我们定义了一个名为`pve`的宏，它展开为"Proxmox VE"。

对于多次使用的URL，应该定义两个宏。

  • {name-url}`, 它只包含了http(s)的URL

  • {name}`，其中包含完整的链接，包括规范描述

例如，宏 {forum-url} 展开为 {forum-url}，宏 {forum} 展开为 {forum}。

计划是为那些被多次使用的术语增加更多此类定义。

Warning
 当asciidoc遇到一个拼写错误的宏名称时，它会静默地丢弃包含该行！

自动生成的CLI命令概要

我们自动为所有手册页生成命令行概述。我们能够做到这一点，因为我们有一个完整的{pve} API声明性定义。我已经将这些生成的文件（*-synopsis.adoc）添加到git仓库中，这样即使没有一个完全安装的{pve}开发环境，也能够构建文档。

风格指南

asciidoc 使用一种相当简单的标记语法来格式化内容。在我们的文档中应遵循以下基本原则。

章节

章节通过使用“双行标题”进行格式化，方法是在标题文本下方添加一行与节标题长度相同的适当字符：

Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~ Level 3: ^^^^^^^^ Level 4 (bottom level): ++

Note
 目前级别4的标题在`manpage`输出中无法正常工作，你可能会希望使用`.SECTION`来代替，这会导致相同的渲染效果，而且无论如何这一级别的标题不会显示在任何索引/目录中。

章节标题应该始终有两个空行在前。标题中的每个单词都应该大写，除了“冠词、并列连词、介词以及不定式中的to，除非它们出现在标题的第一个或最后一个单词”（参见http://web.mit.edu/course/21/21.guide/capitals.htm[Mayfield Electronic Handbook of Technical & Scientific Writing]）。

列表

编号列表

编号列表应该使用隐式编号格式创建：

. 第一层级
.. 第二层级
. 再次第一层级

  1. 一级

    1. 第二层

  2. 再次进入第一层

项目列表

项目列表应该使用 * 符号创建：

* 第一级
** 第二级
* 第一级再次

  • 一级

    • 第二层

  • 再次进入第一层

如果你需要在列表元素的同一级别上有其他元素，你可以使用'+'符号来实现这一点。

. 第一层
.. 第二层
+
另一句话（或区块）在继续的第二层上。
. 又回到第一层了

  1. 一级

    1. 第二层

      另一句话（或段落）持续在第二层级上。

  2. 再次进入第一层

标记列表

标记列表应用于使键值对风格的文本列表更具可读性，例如命令行参数或配置选项：

规则标签列表
首个标签文本：

元素文本段落

第二个标签文本：

另一个元素文本段落。
第一个标签文本

元素文本段落

第二个标签文本

另一个元素文本段落。

水平标签列表
[horizontal]
First Label Text:: 元素文本段落

第二个标签文本:: 另一个元素文本段落。

创建

第一个标签文本

元素文本段落
第二个标签文本

另一个元素文本段落。

FAQ部分使用一种特殊的问题和答案风格来标记列表。

文本和块样式

'asciidoc’提供了广泛的默认文本样式：

  • “强调文本”：通过‘text’创建，用于强调单词和短语

  • Monospaced text`：使用\`text\`创建，用于命令/程序名称、文件路径、内联命令、选项名称和值

  • '强调文本：通过使用\*文本\*创建，用于在节中首次引入概念或名称时强调。'

我们的文档中也使用了不同的内置块样式。

通过在每行前面添加空白，可以直接包含完整的段落。使用这种方式来格式化单独一行的完整命令，例如：

pct set ID -option value

通过用包含至少四个'-'字符的行包围一个段落，其内容将被格式化为列表形式。

使用这个来格式化文件内容或命令输出。

通过在段落开头使用 TIP、NOTE:、WARNING: 或 IMPORTANT:，可以创建特别强调的’提示'、注意、'警告’和’重要’信息：

Tip
 这是一个小费
Note
 这是一条笔记
Warning
 这是一个警告
Important
 这是重要信息

对于这些块（包括列表和段落），可以通过在块前加上 . 字符和标题文本来定义一个块标题：

.Title of List
* 第一个元素
* 第二个元素
* 第三个元素
列表标题

  • 第一个元素

  • 第二元素

  • 第三个元素

例如，可以使用块头添加文件名/路径到文件内容列表中。

在线帮助

每个{pve}安装包含完整的HTML格式文档，该文档随后被用作GUI中各种帮助按钮的目标。

如果你在文档中添加了一个特定条目后想要创建一个指向该条目的帮助按钮，你需要做以下事情：

  • 在您的文档条目前添加一个双方括号中的字符串ID，例如 [[qm_general_settings]]。

  • 重建`asciidoc-pve`脚本和包含你的条目的HTML章节文件

  • 在你想要记录的ExtJS面板中添加一个`onlineHelp`属性，使用上面的字符串，比如`onlineHelp: qm_general_settings`。这个面板必须是PVE.panel.InputPanel的子类。

在调用`make install`后，asciidoc-pve脚本将填充一个JS对象，关联字符串id和一个指向本地HTML文档的链接，而你输入面板的帮助按钮将指向这个链接。

截图

首先，应当指出我们可以在’html’和’wiki’页面上展示屏幕截图，并且可以将它们包含在打印文档中。但是，在手册页内无法渲染屏幕截图。因此，手册页内的屏幕截图应该是可选的，即文本不应依赖于屏幕截图的可见性。你可以通过在段落上设置’thumbnail’属性来包含一个屏幕截图。

[thumbnail="screenshot/gui-datacenter-search.png"]
首先，应当指出...

相应的文件需要位于 images/screenshot 文件夹内，并且应该是 .png 图片格式。我们在打印文档中包含屏幕截图，而 pdftex 使用文件内指定的密度（DPI）。因此，所有屏幕截图应使用相同的密度。我们目前要求密度设置为 146 DPI，这样我们就可以显示宽度为 1024 像素的图像。您不应该包含更大的屏幕截图（尽管这是可能的）。

你可以使用`./png-cleanup.pl`脚本来设置正确的密度。只需使用以下命令导入屏幕截图图像：

# ./png-cleanup.pl screenshot.png images/screenshot/screenshot.png
Tip
 你可以使用`identify -verbose screenshot.png`命令来显示所有图像属性（来自Debian包’imagemagick'）
默认截图布局

我们通常会在段落的右侧以小型缩略图的形式展示截屏。在打印的文档中，我们会在段落之前或者如果段落有标题的话，在标题和文本之间渲染全尺寸的图形。如果段落中包含截屏，通常添加标题是一个好主意。

如果您需要渲染许多屏幕截图，可以将它们放在左侧，这样您可以使用`float`属性来交替缩略图的位置：

[thumbnail="screenshot/gui-datacenter-search.png", float="left"]
如果您需要渲染许多截图...

请避免过多连续的截图，以避免渲染问题。同时，验证打印的文档，查看大型截图是否会造成布局问题。

版权

版权所有 © 2016-2021 Proxmox Server Solutions GmbH

根据GNU自由文档许可证的条款，版本1.3或自由软件基金会发布的任何后续版本，允许复制、分发和/或修改本文档；没有不变部分，没有封面文字，也没有封底文字。许可证的副本包含在链接:LICENSE[LICENSE]文件中。