将文档源码从 reStructuredText 转换为 MyST Markdown

[seisman]

Sphinx 文档默认使用 reStructuredText 语法，但也支持 MyST Markdown 语法。

MyST Markdown 是在标准 Markdown 语法上做了一些扩展，使得其具有更强大的功能。目前我的感受是，MyST Markdown 与 reStructuredText 在功能上是完全等效的，而 MyST Markdown 语法要更简单。

我倾向于将文档源码从 reStructuredText 转换为 MyST Markdown：

1. MyST Markdown 语法可能对新手贡献者更加友好
2. 格式的转换可以通过工具 rst-to-myst 实现
3. Sphinx 支持同时使用 ReST 和 Markdown，所以不必一次性全部都转换
4. 由于 GMT 官方文档还是 ReST，所以模块手册可能还是用 ReST 比较好，方便直接从官方模块文档复制

@gmt-china/contributors

[ZMAlt]

从我的角度看：md 确实比 rst 更加简单，我到现在还要靠查文档写 rst。至于吸引新手贡献嘛，困难挺多的，包括翻墙、github/git，rst 只是其中困难之一，还是需要有极大热情才可能参与贡献。我想比较重要的是第 4 条，除了模块以外，很多需要重新更新、整理、审核的部分，可能还是要复制官方文档 Technical Reference。如果能确定这部分工作量不大，而且已经有的能批量转换，换成 md 也 OK。

[seisman]

至于吸引新手贡献嘛，困难挺多的，包括翻墙、github/git，rst 只是其中困难之一，还是需要有极大热情才可能参与贡献。

至少解决了其中一个问题，其他的问题慢慢解决吧。

除了模块以外，很多需要重新更新、整理、审核的部分，可能还是要复制官方文档 Technical Reference

其他部分应该没有必要复制英文文档

[seisman]

根据#1346 的经验，自动转换步骤如下：

1. rst2myst convert *.rst --config config.yaml
   其中 config.yaml 的内容为:

language: zh_CN
sphinx: true
extensions:
- sphinx_design
#- sphinx_gmt.gmtplot
default_domain: py
consecutive_numbering: true
colon_fences: true
dollar_math: true
conversions:
  sphinx-design.dropdown.DropdownDirective: parse_all
  docutils.parsers.rst.directives.tables.RSTTable: parse_all 
#  sphinx_gmt.gmtplot.GMTPlotDirective: direct

2. 执行 python fixunicode.py *.md

其中 fixunicode.py 的内容为:

from pathlib import Path
import sys

import re

if len(sys.argv) == 1:
    sys.exit(f"Usage: python {sys.argv[0]} files")

# Function to replace Unicode escape sequences with actual characters
def replace_unicode_escape(match):
    return chr(int(match.group(0)[2:], 16))

for file in sys.argv[1:]:
    text = Path(file).read_text()
    converted_text = re.sub(r'\\u[0-9a-fA-F]{4}', replace_unicode_escape, text)
    Path(file).write_text(converted_text)

3. 执行 python fixmeta.py *.md，其中 fixmeta.py 的内容为:

import re
import sys

def convert_front_matter(input_file, output_file):
    # Open the input file for reading
    with open(input_file, 'r', encoding='utf-8') as infile:
        lines = infile.readlines()

    # Initialize variables to track the front matter conversion
    in_front_matter = False
    converted_lines = []
    remaining_lines = []

    # Process each line in the file
    for line in lines:
        if line.strip() == "---":
            # Toggle the in_front_matter flag
            in_front_matter = not in_front_matter
            continue

        if in_front_matter:
            # Convert front matter lines
            match = re.match(r'^\s*["\']?(.+?)["\']?\s*:\s*["\']?(.+?)["\']?\s*$', line)
            if match:
                key = match.group(1).strip()
                value = match.group(2).strip()
                converted_lines.append(f":{key}: {value}")
        else:
            # Append non-front matter lines to the remaining lines
            remaining_lines.append(line)

    # Combine converted lines with the rest of the file
    if len(converted_lines) == 0:
        output_content = "".join(remaining_lines)
    else:
        output_content = "\n".join(converted_lines) + "\n" + "".join(remaining_lines)

    # Write the output to the specified file
    with open(output_file, 'w', encoding='utf-8') as outfile:
        outfile.write(output_content)

for file in sys.argv[1:]:
    convert_front_matter(file, file)

4. 执行 sed -i 's/______________________________________________________________________/---/' *.md
5. 手动编辑 Markdown 文件，将文件开头几行的作者、最近更新日期等信息放在第一个大标题后面

[ZMAlt]

发现问题， rst 页面的贡献者链接失效

[seisman]

发现问题， rst 页面的贡献者链接失效

具体是指哪个页面？

[ZMAlt]

https://docs.gmt-china.org/latest/chinese/windows/
比如这里开始的贡献者

[seisman]

https://docs.gmt-china.org/latest/chinese/windows/ 比如这里开始的贡献者

6ad5230 这个commit应该会修复这个问题

[ZMAlt]

经过 #1349 ， 上面的经验是不是需要更新？

[seisman]

已更新，主要问题出在 gmtplot 这个指令上。

ReST 语法是:

.. gmtplot::

预期的 MyST 语法是：

:::{gmtplot}
:::

但不知为何无法正常生成图片，所以目前只能用 {eval-rest} 把它包起来。

[seisman]

目测现在已经把除模块手册之外的所有rst都转成了md。目前还需要翻看每一页，找到有问题的地方进行修复

[seisman]

我创建了 #1361 来修复文档中的小问题。你发现有问题，可以直接推送到那个分支。