rsyslog-docs

rsyslog 项目文档

rsyslog 文档是使用（Python）Sphinx 文档处理器生成的。rsyslog-doc 项目本身的文档由本 README 以及本文件中链接的其他文档提供。

学习文档工具

如果您不熟悉 rst 和 Sphinx，请参阅 Sphinx 文档开始学习： http://www.sphinx-doc.org/en/stable/contents.html

贡献的软件/内容

在仓库中，您会找到一个 contrib 目录。

尽管此目录中的内容是官方 rsyslog-doc 仓库的一部分，但其状态有所不同。仓库中的其他内容均由开发团队提供全面支持，而 contrib 目录中的内容主要由提供该内容的贡献者负责支持。

内容范围可能从小型一次性脚本到用于自动化文档构建的工具不等。详情请参见 contrib README。

如果您有新内容要添加到该区域，请按照本页面上的文档贡献说明操作，并将您的更改作为新的 Pull Request 提交。

开发团队资源

除了此处的说明外，还有一个单独的 BUILDS_README.md 文件供 rsyslog-doc 团队成员使用。该文档用作那些定期提供文档开发版本和官方发布版本构建人员的快速参考。

文档贡献流程

1. 使用 GitHub 账户登录
2. Fork 官方仓库 https://github.com/rsyslog/rsyslog-doc
3. 基于最新的 master 分支创建一个新分支
4. 进行修改
5. 提交到您 fork 仓库中的新分支
6. 提交 Pull Request (PR) 供审核 (https://github.com/rsyslog/rsyslog-doc/pulls)
7. 提交 Pull Request 供审核后，请停止对新分支的任何修改。相反，在等待文档团队反馈期间，请从您的 master 分支创建一个新分支。
8. 团队成员将审核您的工作并提供反馈。在收到反馈并完成所有必要修改后，您的 PR 将被接受并合并到官方 master 分支。
9. 此时，请删除您提交 PR 所用的分支，并为下一轮工作创建一个新分支。

对于小的修改，完全可以通过 GitHub 网页界面完成。对于较大的修改，具备一些 Git 知识会有所帮助，不过像 Atom 或 Visual Studio Code 等编辑器也为新手提供了更便捷的 Git 交互方式。

在开始工作之前，建议您查看现有的 PR 和开放的 issue，以便与其他贡献者协调工作。

在进行修改的过程中，如有任何问题，请随时联系我们。

提示：如果您希望从较简单的任务入手，请查看标有 good first issue 或 help wanted 的 issue。

请求反馈/帮助

在修改文档时，建议您向社区其他成员寻求意见。您可以通过邮件列表、在 GitHub 上提交新 issue，或（试验性地）通过在 Stack Exchange 上发布问题来实现。

• 邮件列表：http://lists.adiscon.net/mailman/listinfo/rsyslog
• Stack Exchange（试验性）
  • 提问
  • 查看现有问题

构建文档

这些说明假设在 Windows 和 Linux 上默认安装了 Python。由于 Sphinx 项目推荐使用 Python 2.7，因此这里将以此为例进行说明。

假设条件

• 您希望以标准用户身份安装 pip Python 包，这会将已安装的包放置到该用户的主目录中。如果希望为所有用户进行系统范围的安装，请移除 --user 标志。

• 您希望使用虚拟环境将 Sphinx 及其依赖项安装到专用环境中，而不是与系统范围安装的包或使用 --user 标志安装到用户主目录的包一起安装。如果希望为系统所有用户安装 sphinx 包及所有依赖包，则需要以提升权限的用户账户（例如，sudo、su 或在 Windows 系统上具有管理员权限）运行包安装命令。

• 您是首次执行这些步骤。如果要生成文档的更新副本，请省略涉及安装包和应用程序的步骤。

准备环境

此过程的第一部分因操作系统而异。后续步骤完全相同，因此将集中说明。

Linux

1. 从 https://bootstrap.pypa.io/get-pip.py 下载 pip 安装程序

2. 在本地安装 pip，而非系统范围安装

   1. python ./get-pip.py --user

3. 安装 virtualenv 包并创建新的虚拟环境

   1. python -m pip install virtualenv --user
   2. python -m virtualenv rsyslog-docs-build
   3. source rsyslog-docs-build/bin/activate

4. 为您的发行版安装 git。由于不同发行版对软件包的命名不同，您可能需要将以下示例中的软件包名称替换为您发行版的对应软件包名称。

   您需要安装 Git 才能克隆项目仓库、管理您的更改并将其提交以进行审核，最终纳入项目。

   安装 Git 的示例命令：

   • Debian/Ubuntu：apt-get install git-core
   • CentOS/RHEL：yum install git

   更多示例请参见 Pro Git 2 中的安装 Git 章节。

Windows

1. 从 https://bootstrap.pypa.io/get-pip.py 下载 pip 安装程序
2. 从 https://git-scm.com/download/win 下载并安装 Windows 版 Git
3. 在本地安装 pip，而非系统范围安装
   1. c:\python27\python get-pip.py --user
4. 安装 virtualenv 包并创建新的虚拟环境
   1. c:\python27\python -m pip install virtualenv --user
   2. c:\python27\python -m virtualenv rsyslog-docs-build
   3. rsyslog-docs-build\Scripts\activate.bat

Windows 和 Linux

1. 在新的虚拟环境中安装 sphinx 包及其他项目依赖项，而非系统范围安装
   1. pip install -r requirements.txt
2. 克隆官方 Git 仓库
   1. git clone https://github.com/rsyslog/rsyslog-doc.git
3. 检出当前稳定版或开发版（即“master”）分支
   1. cd rsyslog-doc
   2. git checkout BRANCH_NAME_HERE
      • 选择 v8-stable 分支以获取最新稳定版本中当前可用功能的相关内容
      • 选择 master 分支以获取即将推出的功能和修复的相关内容
4. 可选：如果您之前已克隆过仓库，请先运行 git pull 以更新新的更改，然后再继续。

生成文档

1. 生成 HTML 格式
   1. sphinx-build -b html source build
2. 生成 EPUB 格式
   1. sphinx-build -b epub source build
3. 查看生成的内容
   • 在浏览器中打开 rsyslog-doc/build/index.html
   • 使用 Calibre、Microsoft Edge、Okular、Google Play Books 或任何其他 EPUB 兼容的阅读器查看 rsyslog-doc/build/rsyslog.epub 文件