jolielang/docs

Jolie文档仓库指南

1. 仓库概述和主要用途

本仓库用于管理Jolie官方文档，文档在线地址为：<[***]>。

注意：若需更新文档，请勿直接修改主分支。需根据Jolie版本更新对应分支，例如：Jolie 1.10.x 版本的文档需更新 v1.10.x 分支。

2. 核心功能和特性

• 版本化文档管理：通过分支机制维护不同Jolie版本的文档（如 v1.10.x 分支对应 1.10.x 版本）。
• 规范化示例代码：提供统一的命名约定和代码风格，确保文档示例的一致性和可读性。
• 教程维护流程：定义清晰的教程修复和创建流程，包括分支命名、文件组织、图片管理等规范。

3. 使用场景和适用范围

本仓库主要面向Jolie文档贡献者，适用于以下场景：

• 修复现有教程中的错误或优化内容。
• 创建新教程以补充Jolie功能说明或使用案例。
• 标准化文档中的代码示例格式和命名规范。

4. 详细使用方法和配置说明

4.1 贡献指南

4.1.1 示例创建规范

4.1.1.1 命名约定

4.1.1.2 请求消息分配规范

• 优先使用内联语法：尽量简化请求消息赋值，直接内联定义参数。
  推荐：

  jolie
  readFile@file( { filename = "test.txt" } )( response )
  

  不推荐：

  jolie
  request.filename = "test.txt"
  readFile@File( request )( response )
  

• 多行格式化：参数较多时，使用多行排版提高可读性。

  jolie
  writeFile@File( {
    filename = "text.txt"
    content = "this is a test message"
  } )()
  

• 复杂消息处理：当请求消息包含多级节点时，使用深拷贝（<<）或with语句。
  深拷贝示例：

  jolie
  request << {
      node1 = "node1"
      node2 = "node2"
      node3 = "node3"
      ...
  }
  

  with语句示例：

  jolie
  with( request ) {
      node1 = "node1";
      node2 = "node2";
      node3 = "node3";
      ...
  }
  

4.2 修复教程

4.2.1 分支命名规则

创建分支时需遵循格式：tutorials/fix/name-of-the-tutorial（其中name-of-the-tutorial为教程名称）。

4.3 创建新教程

4.3.1 分支命名规则

创建分支时需遵循格式：tutorials/new/short-tutorial-name（其中short-tutorial-name为教程简称）。

4.3.2 操作步骤

步骤1：在 jolie/examples 仓库中操作

1. 创建并切换至分支：

   bash
   git checkout -b tutorials/new/short-tutorial-name
   

2. 进入教程目录：

   bash
   cd examples/v1.10.x/tutorials/
   

3. 创建教程文件夹：

   bash
   mkdir short-tutorial-name
   

4. 进入新文件夹，创建教程所需的所有文件（如Jolie代码示例、配置文件等），完成后提交。

步骤2：在 jolie/docs 仓库中操作

1. 切换至对应版本分支（如 v1.10.x）：

   bash
   git checkout v1.10.x
   

2. 基于该分支创建新分支：

   bash
   git checkout -b tutorials/new/short-tutorial-name
   

3. 进入文档教程目录：

   bash
   cd docs/web/tutorials/
   

4. 创建教程文件夹并进入：

   bash
   mkdir short-tutorial-name && cd short-tutorial-name
   

5. 创建教程文档文件 README.md，内容需包含：
   • 链接至 jolie/examples 仓库中对应示例代码的路径。
   • 引用其他文档页面时，需使用完整URL（而非本地路径）。
   • 如需插入图片，按以下流程处理：
     1. 进入 docs/src/images/，复制一个现有 .svg 文件作为模板，重命名为新文件名。
     2. 使用 Inkscape 编辑图片：
        • 注释文本使用字体 Segoe Print。
        • 注释与图形的连接线使用“自由手绘工具”（斜角效果设为50左右）。
        • 微服务间的连接线使用直线工具。
     3. 保存编辑后的 .svg 文件至 docs/src/images/（源文件）。
     4. 导出 .png 文件至 docs/web/assets/。
     5. 在文档中引用 .png 文件，示例链接格式：

        markdown
        ![](https://raw.githubusercontent.com/jolie/docs/v1.10.x/web/.gitbook/assets/using_dependencies_01.png)
        

6. 编辑 docs/web/SUMMARY.md，在“Tutorial”章节下添加新教程链接，注意教程顺序需符合知识递进逻辑（确保前置教程已提供必要的基础知识）。

4.3.3 提交贡献

完成文档编辑后，提交Pull Request至对应版本分支。