Apache OFBiz Documentation Guidelines

### Apache OFBiz 文档编写指南总结 #### 1. 文档配置 - **独立文档**：作为独立指南发布的文档（如开发者手册、用户手册）需要包含通用配置，以确保输出格式一致。 - **配置内容**： - 图片目录：`:imagesdir: ./images` - PDF渲染配置：`:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in, align=center]` - 使用 Rouge 语法高亮器。 - **全局配置**（在 Gradle 构建文件中设置）： - `doctype`: 'book' - `revnumber`: 'Trunk' - `icons`: 'font' - `sectnums`: '' - `chapter-label`: '' - `toc`: '' - `toclevels`: '5' #### 2. 许可证 - 文档使用 Apache 2.0 许可证，具体如下： ``` Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` #### 3. 引入 - 文档指南作为风格指南和示例集合，非完整用户手册。 - 参考资源： - [AsciiDoc 用户指南](http://asciidoc.org/userguide.html) - [AsciiDoc 作者指南](https://asciidoctor.org/docs/asciidoc-writers-guide/) - [AsciiDoc 快速参考](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) - [AsciiDoc 推荐实践](https://asciidoctor.org/docs/asciidoc-recommended-practices/) #### 4. 包含文件 - 使用标签包含部分文件： ```adoc # tag::tagname[] This should be included! # end::tagname[] ``` 包含方式：`include::resource/article.adoc[tags=tagname]` #### 5. 图像导入 - HTML 输出：`image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=3.0in, align=left]` - PDF 输出：图片路径由文档头配置，无需重复指定。 - 内联图片：`image:OFBiz-Logo.svg[Apache OFBiz Logo, width=40%]` #### 6. 代码格式化 - 支持多种编程语言的语法高亮，如： - Java： ```adoc [source,java] ---- public class Foo { public String bar; public String bar() { return bar; } } ---- ``` - 带编号的代码： ```adoc [source,java] ---- 1 public class Foo { 2 public String bar; 3 4 public String bar() { 5 return bar; 6 } 7 } ---- ``` - 带解释的代码： ```adoc public class Foo { public String bar; ① public String bar() { return bar; ② } } ``` - ① 声明 `bar` 字段 - ② 返回 `bar` 值 #### 7. 其他示例 - XML 示例： ```xml Lazarus het Draeke ``` - CSS 示例： ```css body { background: transparent url(/images/ofbiz_logo.png) no-repeat scroll left top; color: #000; font-family: Verdana, Arial, Helvetica, sans-serif; font-size: .75em; line-height: 1.5em; padding: 50px 0 0; bgcolor: #ffffcc; } ``` - JavaScript 示例： ```javascript function msg() { alert("Hello OFBiz"); } ``` - JSON 示例： ```json { "id": 1, "name": "A green door", "price": 12.50, "tags": ["home", "green"] } ``` - SQL 示例： ```sql SELECT * FROM FOO; ``` #### 8. 文件组织 - 每个应用有一个主文件，位于 `src/docs/asciidoc` 目录。 - 包含文件位于 `src/docs/asciidoc/_include`。 - 示例目录结构： ``` src |- docs |- asciidoc |- _include |- images |- ${componentName} ``` #### 9. 其他注意事项 - 每个 `.adoc` 文件需包含 Apache 许可证头，放置在 `//// license… ////` 之间。 - 文档编写需遵循指南中的风格和格式要求，确保内容准确且易于理解。