跳到内容

编写文档

收件人阅读文档，转到docs.civicrm.org网站获取所有活动文档的最高级列表。

本页介绍CiviCRM中文档系统的详细信息以及如何贡献。我们还有更多基本概述如何为本指南或用户指南做出贡献。

注意：此处不包括wiki

这个维基历史上一直是CiviCRM的文档系统，但自2017年起已逐步淘汰。本页其余部分仅介绍MkDocs指南，不包括涉及wiki的文档流程。无法在wiki上创建新文档。

何时记录

如果你是为核心做出贡献更新文档和更改是确保CiviCRM长期可用性和可维护性的重要步骤。

并非所有更改都需要文档更新。以下是一些指导原则：

  • 文件几乎应始终随附新功能.
    • 请记住，有些功能是用户-面对（因此需要用户指南中的新文档），而有些功能是开发商-面（因此需要《开发人员指南》中的新文档。）
  • 错误修复有时需要更新文档。检查现有文档以查看可能需要的更改。

提示

尝试编写文档之前编写代码！然后，您就有了一种方法来组织您的想法并衡量该功能是否有效。

如果你是提交核心请求并希望提交随附的文档更改，请在两个拉请求中提供注释以供交叉参考。在首先合并核心PR之前，不会合并您的文档PR。

MkDocs中的指南

我们正在使用Mk文档制作指南。这些指南的内容都写在降价存储在文本文件中，并托管在GitLab的存储库中。然后，指南将自动发布到docs.civicrm.org使用我们的自定义出版系统.

版本

我们不再维护特定版本的文档，我们维护常绿植物始终跟踪CiviCRM最新版本的文档，但在适当的情况下，指明出现新功能和重大更改的版本。例如：

从CiviCRM 5.37.0版可以在以下网址找到ReCAPTCHA配置管理->自定义数据和屏幕->ReCAPTCHA。在早期版本的CiviCRM中，这位于“杂项设置”页面上。

如果您正在改进当前文档，请编辑主人或主要的分支。

语言文字

指南可以有多种语言，我们对不同的语言使用不同的存储库。例如，您可以单击查看所有X版并查找其他语言的存储库。

为文档提供帮助

我们欢迎对文档的贡献，无论大小！

资源：

在开始编辑之前，您可以在以下资源中找到有用的信息：

提交问题

最简单的帮助方式是描述你认为的变化应该通过在问题队列中为lab.civicrm.org实验室你正在阅读的指南。然后有人会看到你的问题并采取行动，希望能尽快。每个指南都有自己的问题队列。首先找到指南的lab.civicrm.org存储库，可以在各自的文档指南中找到(用户指南,《系统管理员指南》,开发人员指南)位于导航栏的右角。在查看lab.civicrm.org时，单击“问题”。您需要在lab.civicrm.org上创建一个帐户才能提交新的问题，但创建一个新问题是快速而免费的。

通过lab.civicrm.org编辑

请参阅中使用Git编辑的文档CiviCRM用户指南.

使用MkDocs进行本地测试

编写指南的最高级方法是使用git将所有降价文件下载到您的计算机上，在本地编辑它们，使用预览更改Mk文档，然后使用git将这些更改推送到您的个人分叉，最后在主存储库上发出“拉请求”。这种方法使编辑变得非常快速和简单，但确实需要一些设置，以及一些关于git工作原理的知识。

  1. 获取要编辑的指南的源文件

    1. 在上查找存储库lab.civicrm.org实验室 （请参阅您正在阅读的文档屏幕右上角的“实验室”链接）
    2. 转到lab.civicrm.org上的存储库。

    3. 克隆你的叉子将存储库的

      git克隆https://lab.civicrm.org/Your用户名/civicrm-dev-docs.git光盘公民发展组织

  2. （可选）如果你有码头工人安装后，此时您可以运行以下命令之一，然后跳到下面的“在本地查看指南…”步骤。

    1. 对于拥有完整的Windows/Mac/Linux Docker环境的用户，请运行以下命令：

      docker运行--rm-v“$PWD:/docs”-p 8000:8000-w/docs“mjcoltd/civicrm-docker-mkdocs”serve--dirtyreload-a 0.0.0:8000

      并跳到下面的“查看指南”步骤。要定期更新此docker映像，请在执行上述命令之前运行以下命令。

    码头工人rmi mjcoltd/civicrm-docker-mkdocs

    1. 对于那些拥有传统或“家庭”操作系统（Windows 7、8.1、10家庭高级版）的人来说，情况有点复杂。如果您已经使用Oracle VM VirtualBox或VMWare工具在系统上实现了虚拟机，情况也是如此。这些工具不能很好地与本机Windows HyperV虚拟化配合使用。在任何情况下，请遵循以下步骤：

      1. 检查GitHub文件夹是否位于以下路径中：c： \Users\<用户名>\Documents\。。。如果是，一切都好；如果没有，请将其移到那里，并编辑GitHub配置以反映更改的位置。
      2. 设置Docker-Toolbox环境（依赖于Oracle VM VirtualBox），并检查它是否正常工作（Hello-world容器正常工作）。
      3. 查看Oracle VM VirtualBox中的Docker-Toolbox实例，确保其具有必要的端口转发配置。如果没有HTTP端口转发规则，请添加一个指定的规则：名称：HTTP，协议：TCP，主机IP:127.0.0.1，主机端口：8000，来宾IP（空），来宾端口：8000。如果不存在此配置，则所有打开浏览器会话的尝试都将收到“连接被拒绝”错误。
      4. 运行此命令：

      docker run--rm-v“/c/Users/<username>/Documents/GitHub/civicrm-user-guide:/docs”-p 8000:8000-w/docs mjcoltd/civicrm-docker-mkdocs serve--dirtyreload-a 0.0.0:8000
      并跳到下面的“本地查看指南…”步骤。

  3. 安装pip（点阵）（python包管理器）

    • 操作系统X：brew安装python3
    • Debian/Ubuntu：sudo apt-get安装python3-pip

  4. 安装MkDocs，以及材料主题和Pyagms语法高亮显示.

    sudo pip安装mkdocs公司==10.4 mkdocs材料==4.6.3

  5. 使用MkDocs提供指南的本地副本

    1. 运行：

      mkdocs服务
      • 如果你得到[Errno 98]地址已被使用然后尝试使用不同的端口mkdocs服务-本地主机：8001

  6. 在浏览器中本地查看指南http://localhost:8000.

  7. 编辑降价有你选择的编辑。作为你保存您的更改mkdocs公司将自动重新处理页面并刷新浏览器。

  8. 当你对自己的编辑感到满意时，使用git提交并将更改推送到你的fork。然后在lab.civicrm.org上提交一个pull请求。

  9. Ctrl键-C类将停止MkDocs服务器。

添加新页面

  1. 请确保您已设置为使用MkDocs进行本地编辑
  2. 决定它在菜单中的位置。（在文档通道如果你不确定。）
  3. 通过在中适当添加新行，为新页面添加菜单位置mkdocs.yml文件.
    • 按照此文件其他行上的模式指定标题和文件位置。
    • 设置标题时，请记住，相同的标题将显示在菜单和读者的浏览器选项卡标题中，因此选择一个简短但在一定程度上也独立的标题。
    • 为新页面指定降价文件的位置，该文件遵循您所决定的菜单位置的文件夹结构。
  4. 在新菜单项指定的位置添加新的降价文件，并开始向其添加内容。
  5. 如果您要从其他来源（如wiki、StackExchange等）复制现有内容，请按照提供归属的说明

移动页面

如果要移动页面，请执行以下步骤：

（提前）如果您对页面有更改内容，然后在分离git提交。

  1. 移动文件。
  2. 更新mkdocs.yml文件使用页面的新路径。
  3. 将重定向规则添加到重定向/internal.txt.
    • 格式为旧的/页/路径新的/页/path
    • 使用路径的一部分之后这个文档目录。
    • 不要使用前导斜杠或尾随斜杠
    • 不要使用.md文件延伸
    • 首先列出旧路径，然后列出新路径
    • 用空格分隔路径
  4. 运行mkdocs服务看看它是否会对断开的超链接发出任何警告。如果是这样，那就去修。

注释

页面重定向不会在本地工作（使用预览时mkdocs服务)，但它将一旦指南在docs.civicrm.org上发布，就可以工作了。重定向是作为我们的文档发布者应用程序。

自动生成的文档

一些指南可能有自动生成的内容，这里对此进行了总结。

在开发人员指南中

此开发人员指南具有自动生成的所有挂钩列表。要重新创建此列表，请从存储库的根级别运行以下命令：

./bin/tools生成：挂钩列表

我们的编辑工作流目前要求有人在编辑hook文件后手动运行此命令，并提交其更改。

内容归属准则

所有CiviCRM文档内容均已获得许可抄送BY-SA 3.0。这意味着，如果您想从我们的文档中复制内容并在其他地方使用，只要您将其归因于作者，我们欢迎您这样做。

如何获取指南内容的作者信息

当您想要复制内容时，这是相关的由于我们的文档书籍。

  1. 查找lab.civicrm.org实验室包含要使用的内容的书籍的存储库。（通常在每个页面的右上角都会有指向此存储库的链接。）
  2. 导航到lab.civicrm.org中相应的降价文件（它将与发布内容的URL路径相匹配）。
  3. 单击“责任”，逐行查看有关内容作者的详细信息。

如何显示迁移内容的属性进入之内我们的书

这个CivicCRM维基和堆栈交换也可以使用CC BY-SA 3.0许可证，这很方便，因为内容会定期从这些来源迁移到我们的MkDocs指南中。但为了遵守许可，我们必须将原始内容作者归为

将内容迁移到需要属性的文档指南时，请在页面底部显示此属性，如下所示：

## 信用

一些 内容 从 这 第页 是 已迁移 从 其他 来源
和 贡献 通过 这个 下列的 作者:

* 米奇 鼠标
* 丽莎 辛普森
* 大 鸟

提交消息还应引用原始内容的URL。