Apache OFBiz Documentation Guidelines

• 语言: 英语
• 格式: .pdf
• 来源: ofbizextra.org

摘要

This document provides guidelines for documenting the Apache OFBiz project. It covers document configuration, image importation, FAQ and glossary creation, and code formatting using Asciidoc. The guidelines include global image directory definitions, title logo placement, source code highlighting, and specific formatting examples for Java, Groovy, XML, CSS, and JavaScript. It also outlines how to include partial files and manage experimental features.

AI总结

### Apache OFBiz 文档编写指南总结

#### 1. 介绍
- 该指南为 Apache OFBiz 项目提供通用的编写规范和示例。
- 主要参考文档包括：AsciiDoc 用户指南、AsciiDoc 作者指南、AsciiDoc 快速参考和AsciiDoc 推荐实践。
- 鼓励贡献者参与文档编写，并参考指定的Wiki页面了解更多信息。

#### 2. 通用规则
- **文档配置**：独立发布的文档需要包含通用配置，确保输出格式一致。非独立文档可继承父文档的配置。
- **Apache 许可证头**：每个 `.adoc` 文件必须包含 Apache 许可证头，置于 `/// license... ///` 之间。
- **文件组织**：每个应用对应一个主文档文件，位于 `src/docs/asciidoc` 目录，并包含其他文件（如 `src/docs/asciidoc/_include` 中的文件）。

#### 3. 文档配置
- **独立文档**：包含以下配置项：
- 图片目录定义：`:imagesdir: ./images`
- PDF 渲染配置：标题 Logo 和代码高亮器（Rouge）。
- 全局配置项（位于 `build.gradle`）包括：`doctype`、`revnumber`、`experimental`、`icons`、`sectnums`、`chapter-label`、`toc` 和 `toclevels`。

#### 4. 版权声明
- 每个 `.adoc` 文件需包含 Apache 许可证头，具体如下：

  /// Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements...

#### 5. 文件组织
- 文档结构示例：

  src
  |- docs
     |- asciidoc
        |- _include
        |- images
        |- {componentName}

#### 6. 代码格式
- 支持多种编程语言的代码高亮，例如 Java、Groovy、XML、CSS 和 JavaScript。
- 示例：
- Java 代码高亮：

    [source,java]
    public class Foo {
      public String bar;
      public String bar() {
        return bar;
      }
    }

- 带注释的代码：

    [source,java,role=""]
    public class Foo {
      public String bar; ①
      public String bar() {
        return bar; ②
      }
    }

#### 7. FAQ 和 Glossary
- **FAQ**：使用带 ID 的列表编写，支持列表内链接。
示例：

  [#faq_entry_1] FAQ 入门 1:: 这是示例 FAQ 的第一条。

- **Glossary**：每个组件和用户手册应有一个 glossary，ID 为大写且用 `_` 替换空格。

#### 8. 图片导入
- 图片导入格式：
- HTML 输出：`image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=3.0in, align=left]`
- 行内图片：`image:OFBiz-Logo.svg[Apache OFBiz Logo, width=40%]`

#### 9. 部分文件包含
- 使用标签包含部分文件：

  # 标签定义
  This should be included!
  # 标签引用
  include::resource/article.adoc[tags=tagname]

#### 10. 图标使用
- 使用 Font Awesome 图标：
- 示例：`icon:battery-full[set=fas]` 和 `icon:file[set=fas]`

#### 11. 目录配置
- **TOC 配置**：`toclevels` 设置为 `5`，表示最多显示 5 级目录。

#### 12. 总结
- Apache OFBiz 文档指南提供了从配置、编写规范到具体实现的全面指导，确保文档的一致性和可读性。