README

此仓库包含 CiviCRM 使用以托管和更新使用 MkDocs 构建的各个文档书籍的源代码，并发布到 docs.civicrm.org。

您可能还希望

• 阅读 这些文档书籍 （以及其他文档来源）
• 贡献 文档内容
• 添加 新的文档书籍

定义新的书籍

此信息/内容已移动到新的仓库。点击此处查看 docs-books 仓库。

发布书籍更新

当相应的分支在其仓库中更新时，书籍会自动发布。这通常是通过进行编辑并提交拉取请求来实现的。任何作为拉取请求一部分提交的提交中的电子邮件列表都将收到一个更新过程摘要的电子邮件。

设置自动发布

GitHub

通过在 GitHub 仓库内的钩子配置自动更新。您需要成为该仓库的所有者（而不仅仅是协作者）才能执行这些步骤。

1. 转到 https://github.com/[用户或组名]/[仓库名]/settings/hooks/new
2. 将 有效负载 URL 设置为 https://docs.civicrm.org/admin/listen
3. 将 内容类型 设置为 'application/json'
4. 将 您想触发此 webhook 的事件 设置为 '让我选择个别事件' 并选择 'Pull request' 和 'Push'（因为这些都是应该触发更新的唯一事件）

GitLab

1. 转到 https://lab.civicrm.org/[用户或组名]/[仓库名]/settings/integrations
2. 将 URL 设置为 https://docs.civicrm.org/admin/listen
3. 将 触发器 设置为 'Push events' 和 'Tag push events'。

手动发布

如果需要，可以通过调用以下格式的 URL 手动更新书籍。

https://docs.civicrm.org/admin/publish/{book}/{lang}/{branch}

• {book} 书籍的名称 - 如 conf/books 目录中的配置文件所述。
• {lang} 您希望发布的语言 - 如配置文件 （可选） 中定义。
• {branch} 您希望发布的分支名称 - 需要是该语言的仓库中的分支 （可选）。

安装文档基础设施的本地副本

Docker

该仓库包含一个 dockerfile，您可以使用它创建一个容器，该容器包含运行应用程序所需的一切。

要构建容器并安装 composer 依赖项，请从项目目录运行

docker build -t docs-publisher .
docker run --rm -v $PWD:/var/www docs-publisher composer install --working-dir=/var/www

然后运行它

docker run --rm -v $PWD:/var/www -p 8080:8080 docs-publisher

如果您已经有一个东西在 8080 端口上监听，则可能需要更改端口参数中的第一个 8080。

容器中的 nginx 用户需要能够写入这些目录。

sudo chmod -R a+rw var/cache var/logs/ web/dev/ var/repos/

您应该能够在 http://localhost:8080 上看到应用程序。

在您的宿主机上

注意：以下步骤仅对负责 CiviCRM 文档 基础设施 的人有用和必要。如果您只想 贡献文档内容，则不需要这样做。

1. 安装先决条件：注意：示例命令已在Ubuntu 16.04和18.04上测试过。

   • nginx:

     sudo apt install nginx
     

   • curl:

     sudo apt install curl
     

   • unzip:

     sudo apt install unzip
     

   • php 7.4:

     sudo apt install software-properties-common
     sudo add-apt-repository ppa:ondrej/php
     sudo apt update
     sudo apt install php7.4-fpm php7.4-cli php7.4-gd php7.4-imagick php7.4-json php7.4-mbstring php7.4-opcache php7.4-readline php7.4-tidy php7.4-xml php7.4-xmlrpc php7.4-zip
     

   • pip:

     sudo apt install python3-pip
     

   • composer

     php -r "copy('https://getcomposer.org.cn/installer', 'composer-setup.php');"
     php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
     php composer-setup.php
     php -r "unlink('composer-setup.php');"
     sudo mv composer.phar /usr/local/bin/composer
     

   • mkdocs-material

     sudo -H pip install mkdocs-material==7.3.0
     

     注意：请确保MkDocs以root用户安装，以便可以从src/publish.php脚本（通常以https://docs.civicrm.org/publish.php调用）访问。

2. 将此仓库克隆到类似/var/www/civicrm-docs的位置，并使用composer进行安装

    git clone https://lab.civicrm.org/documentation/docs-publisher.git /var/www/civicrm-docs
    cd /var/www/civicrm-docs
    composer install
   

3. 设置web/static的适当权限

4. 使用examples/nginx中的示例配置文件创建一个用于docs-publisher网站的nginx配置文件。您需要检查/调整PHP套接字路径和根路径。

5. 配置nginx虚拟主机

    ln -s /etc/nginx/sites-available/civicrm-docs /etc/nginx/sites-enabled/
   

6. 获取文档书籍文件

    cd /var/www/civicrm-docs/
    git clone https://lab.civicrm.org/documentation/docs-books.git books
   
   

7. 重新加载您的nginx配置，您应该已经启动并运行。

调试

您需要安装和配置xdebug以从IDE进行调试。在这种情况下，我们假设您正在使用PHPStorm。

docker镜像已预安装和配置了xdebug。从那里，您需要采取以下步骤才能使其正常工作

• 从“设置 > 语言和框架 > PHP > 调试”将xdebug端口更改为9000
• 从“设置 > 语言和框架 > PHP > 服务器”添加一个新的服务器，名称自定，主机为“localhost”，端口为8080。
• 在同一屏幕上启用路径映射，并将项目目录映射到“绝对路径在服务器上”下的“/var/www”。
• 为chrome或firefox安装xdebug辅助工具，如果需要，设置IDE密钥为“PHPSTORM”。
• 启用xdebug辅助工具，在web/app_dev.php中设置一个断点，然后访问http://localhost:8080，调试器应打开PHPStorm。