From 70856b64d46b2c7d4df9ba1e59e6e2992dc1d824 Mon Sep 17 00:00:00 2001 From: 简律纯 Date: Fri, 2 Aug 2024 00:08:13 +0800 Subject: docs!: rebuild with readthedocs and sphinx-build --- docs/API.md | 26 -------------- docs/Element.md | 9 ----- docs/Event.md | 21 ------------ docs/Makefile | 4 +-- docs/Term.md | 75 ---------------------------------------- docs/index.md | 68 ------------------------------------ docs/requirements.txt | 14 ++++---- docs/source/API.rst | 26 ++++++++++++++ docs/source/Element.rst | 9 +++++ docs/source/Event.rst | 21 ++++++++++++ docs/source/Term.rst | 61 +++++++++++++++++++++++++++++++++ docs/source/conf.py | 79 ++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ 13 files changed, 296 insertions(+), 208 deletions(-) delete mode 100644 docs/API.md delete mode 100644 docs/Element.md delete mode 100644 docs/Event.md delete mode 100644 docs/Term.md delete mode 100644 docs/index.md create mode 100644 docs/source/API.rst create mode 100644 docs/source/Element.rst create mode 100644 docs/source/Event.rst create mode 100644 docs/source/Term.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst (limited to 'docs') diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 9022bc2..0000000 --- a/docs/API.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: API Reference ---- - -## ES 1.0 - -### API - -#### 1. `get_version` - -| Method | field | type | notes | -| :-: | :-: | :--: | :----: | -| GET | 无 | | | - -| Output | field | type | notes | -| :-: | :-: | :--: | :----: | -| | ESV | list | 符合语义化版本2.0.0规范的数组[^1] | -[^1]: https://github.com/HydroRoll-Team/echo/blob/main/docs/index.md#版本 - -示例: - -```json -{ - "ESV": [1, 0, 0] -} -``` diff --git a/docs/Element.md b/docs/Element.md deleted file mode 100644 index 21e3f8d..0000000 --- a/docs/Element.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Element ---- - -## ES 1.0 - -### Element - -.. diff --git a/docs/Event.md b/docs/Event.md deleted file mode 100644 index ae7fb01..0000000 --- a/docs/Event.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Event ---- - -## ES 1.0 - -### Event - - -#### 1. Workflow - - -#### 2. Message - - -#### 3. Notice - - -#### 4. Callback - - diff --git a/docs/Makefile b/docs/Makefile index 5607373..08a2dd0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,11 +20,11 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @pdm run $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) # update translation command translate: - @$(SPHINXINTL) update -p ./build/gettext -l $(lang) $(O) + @pdm run $(SPHINXINTL) update -p ./build/gettext -l $(lang) $(O) # build docs docs build: diff --git a/docs/Term.md b/docs/Term.md deleted file mode 100644 index 08a1d2f..0000000 --- a/docs/Term.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Term ---- - -## ES 1.0 - -### Term - -> [!IMPORTANT] -> -> Echo 标准只作用于多人聊天窗口(Window)。 - - -#### Window - -窗口(Window)，一个能呼出水系骰子并能与之交互且能提供消息显示与聊天输入功能的窗体被称为聊天窗口，简称窗口。 - - -#### World - -广义上，一个包含多个(至少两个)用户的聊天窗口即为一个 World(世界)。你可以将此类比为 QQ 平台的群聊(Group)或者 KOOK/Discord 平台的频道(Channel)——但是在(水系)这里，它们都统一被称为 World。 - -> [!WARNING] -> -> 单人群聊不能算作一个世界，即使此群聊有一个骰子且一个用户，也不能成为一个世界，只有用户量 >= 2 且能够与水系骰子交互时才算是一个世界。 - - -#### Sub-world/Main-world - -狭义上讲，一个 World 应该在一段时间内只保持(也必须保持)一个规则包的绑定，因此类似于秘密团那样临时创建的分群或分频道并不能说是一个标准的 World，这类窗口我们称为 Sub-world(子世界)，因此当涉及到 Sub-world 时，我们不能称主群/主频道 为World，而至少应该说是 Main-world(主世界)。 - - -#### Node - -Node(节点) 描述 ES 的实现端，这是它们的统一称谓。同时，通过 ES 所规定的 Events 传递的方向，可以扩展称为 1号节点(Node-1)、2号节点(Node-2) 甚至 3号节点(Node-3)...但是一般来说，两个节点已经足够使用了，Events 的传递方向总是由数字小的节点传递到数字大的节点，若 Events 能在节点间的传递过程中完成给定的任务，则这样的节点传递过程被成为一套完整的 pipeline。 - - -#### Pipeline - -管线(Pipeline)，或称“流水线”。这个概念可能比较抽象，因此在这里给出一个生动的形容——Pipeline，你土味一点，可翻译成“一条龙服务”；专业一点，叫它“综合解决方案”。 - -总之，一个 pipeline，一定是完整的，但不一定是闭合的。 - - -#### Event - -Event(事件)只存在于节点之间。事件划分为 Specific-events(具体事件，例如消息事件、世界人数增减事件等) 与 Abstract-events(抽象事件，例如工作流事件、回调事件等)。具体可翻阅事件一览表 [Events.md](./Event.md) 查看所有 ES 1.0 所支持的事件。 - - -#### Element - -Element(元素)尤其指代包含在 Events 中的各类可以被抽象出来的概念，比如文本(Text)、图片(Image)、富文本(RichText)、音频(Audio)、视频(Vedio)等。具体可翻阅元素列表 [Elements.md](./Element.md) 查看所有 ES 1.0 定义的元素。 - - -#### API - -是指节点(尤其是 Node-2)需要实现的一些网络接口规范。具体参阅 ES 1.0 API列表 [API.md](./API.md)。 - - -#### Without bells and whistles - -没有花里胡哨的方法（不添加不必要，冗余的东西）。 - - -#### Off-the-shelf - -已有的，现成的。 - -#### end to end - -端到端(e2e)，给定一个输入，再给出一个输出，不管其中的过程多么复杂，但只要给了一个输入，那么对应一个输出。 - -#### Priority - -优先级(priority)，作用在 Events 中，尤其是 [Workflow Events]()。 diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index ca107b3..0000000 --- a/docs/index.md +++ /dev/null @@ -1,68 +0,0 @@ -## 一、Echo 规范 - -ES 1.0.0 是 Echo 规范的第一个投入生产环境的版本，而 Echo 是水系规定 HydroRoll 与 infini 之间事件传参类型的一个内部标准，全称 Event Communication and Harmonization across Online platforms。 - -### 1.1 版本 1.0.0 - -文档里的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 都遵循 [BCP 14]、[RFC2119]、[RFC8174] 里的解释说明。 - -[BCP 14]: https://www.rfc-editor.org/info/bcp14 -[RFC2119]: https://datatracker.ietf.org/doc/html/rfc2119 -[RFC8174]: https://datatracker.ietf.org/doc/html/rfc8174 - - -## 二、介绍 - -Echo 规范（ES），是定义一个标准的、与具体编程语言无关的 RESTful API 与 Event Defined 规范。文字跑团(TRPG)游戏是一种基于文字描述和角色扮演的桌上游戏，通常由一个游戏主持人(KP)和多个玩家(PC)组成，通过网络平台进行交流和互动。不同的平台可能有不同的功能和限制，比如群聊、频道、图片、音频甚至视频等，这些都会影响到游戏的体验和效果。为了让水系的文字跑团游戏能够跨平台运行，ES 规定了游戏的数据结构、接口定义、错误处理等。这样，水系用户的 TRPG 游戏就可以在不同的平台上实现相同或相似的功能，同时也可以方便模型或规则包或插件开发者进行扩展和定制。 - - -## 三、术语定义 - -### 3.1 ES 文档 - -一（或多）份用来定义或描述一个 Event 以及 API 的文档。 - -### 3.2 Media Types - -媒体类型定义分散于多处。 媒体类型定义应当符合RFC6838。 - -以下是一些媒体类型定义的示例： - -``` -text/plain; charset=utf-8 - application/json - application/vnd.github+json - application/vnd.github.v3+json - application/vnd.github.v3.raw+json - application/vnd.github.v3.text+json - application/vnd.github.v3.html+json - application/vnd.github.v3.full+json - application/vnd.github.v3.diff - application/vnd.github.v3.patch -``` - -### 3.3 HTTP状态码 - -HTTP状态码被用来表示一次请求的被执行状态。[RFC7231] 定义了有效的状态码，可以在 [IANA Status Code Registry] 找到已经被注册的状态码的列表。 - -[RFC7231]: http://tools.ietf.org/html/rfc7231#section-6 -[IANA Status Code Registry]: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml - -### 3.4 其他术语 - -包含 Window、World、Event、Element等词条，详见 [Term.md](./Term.md)。 - - -## 四、规范 - -### 版本 - -开放 API 规范使用符合[语义化版本 2.0.0](http://semver.org/spec/v2.0.0.html)(semver)规范的版本号。版本号由三部分组成：主版本号.次版本号.修订号。每次更新文档时，根据以下规则递增版本号： -* 主版本号：当 API 有不兼容的修改时，递增主版本号，例如从 1.0.0 变为 2.0.0。 -* 次版本号：当 API 有向下兼容的功能新增时，递增次版本号，例如从 1.0.0 变为 1.1.0。 -* 修订号：当 API 有向下兼容的问题修正时，递增修订号，例如从 1.0.0 变为 1.0.1。 -支持开放API规范 1.0 的工具应该兼容所有 1.0.* 的版本，工具不应当关注修订版本号，比如 1.0.0 和 1.0.1 对它来说应该没有任何区别。 - -此后开放 API 规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此 1.1.0 版本的规范应当可以在面向 1.0.0 版本规范开发的工具内使用。 - -任何兼容开放 API 规范 1.*.* 的文档应当包含一个 echo 字段用来表明它使用的规范的语义化版本。 diff --git a/docs/requirements.txt b/docs/requirements.txt index 899492a..6b39a20 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -furo>=2023.3.27 -sphinx-autobuild>=2021.3.14 -myst-parser>=0.18.1 -sphinx>=5.3.0 -tomli -sphinx_design -sphinx-intl>=2.1.0 \ No newline at end of file +furo>=2024.7.18 +sphinx-autobuild>=2024.4.16 +myst-parser>=3.0.1 +sphinx>=7.4.7 +tomli>=2.0.1 +sphinx_design>=0.6.0 +sphinx-intl>=2.2.0 \ No newline at end of file diff --git a/docs/source/API.rst b/docs/source/API.rst new file mode 100644 index 0000000..9022bc2 --- /dev/null +++ b/docs/source/API.rst @@ -0,0 +1,26 @@ +--- +title: API Reference +--- + +## ES 1.0 + +### API + +#### 1. `get_version` + +| Method | field | type | notes | +| :-: | :-: | :--: | :----: | +| GET | 无 | | | + +| Output | field | type | notes | +| :-: | :-: | :--: | :----: | +| | ESV | list | 符合语义化版本2.0.0规范的数组[^1] | +[^1]: https://github.com/HydroRoll-Team/echo/blob/main/docs/index.md#版本 + +示例: + +```json +{ + "ESV": [1, 0, 0] +} +``` diff --git a/docs/source/Element.rst b/docs/source/Element.rst new file mode 100644 index 0000000..21e3f8d --- /dev/null +++ b/docs/source/Element.rst @@ -0,0 +1,9 @@ +--- +title: Element +--- + +## ES 1.0 + +### Element + +.. diff --git a/docs/source/Event.rst b/docs/source/Event.rst new file mode 100644 index 0000000..ae7fb01 --- /dev/null +++ b/docs/source/Event.rst @@ -0,0 +1,21 @@ +--- +title: Event +--- + +## ES 1.0 + +### Event + + +#### 1. Workflow + + +#### 2. Message + + +#### 3. Notice + + +#### 4. Callback + + diff --git a/docs/source/Term.rst b/docs/source/Term.rst new file mode 100644 index 0000000..5281582 --- /dev/null +++ b/docs/source/Term.rst @@ -0,0 +1,61 @@ +Term +==== + +.. important:: + + Echo 标准只作用于多人聊天窗口(Window)。 + + +Window +^^^^^^ + +窗口(Window)，一个能呼出水系骰子并能与之交互且能提供消息显示与聊天输入功能的窗体被称为聊天窗口，简称窗口。 + + +World +^^^^^ + +广义上，一个包含多个(至少两个)用户的聊天窗口即为一个 World(世界)。你可以将此类比为 QQ 平台的群聊(Group)或者 KOOK/Discord 平台的频道(Channel)——但是在(水系)这里，它们都统一被称为 World。 + +.. warning:: + + 单人群聊不能算作一个世界，即使此群聊有一个骰子且一个用户，也不能成为一个世界，只有用户量 >= 2 且能够与水系骰子交互时才算是一个世界。 + + +Sub-world/Main-world +-------------------- + +狭义上讲，一个 World 应该在一段时间内只保持(也必须保持)一个规则包的绑定，因此类似于秘密团那样临时创建的分群或分频道并不能说是一个标准的 World，这类窗口我们称为 Sub-world(子世界)，因此当涉及到 Sub-world 时，我们不能称主群/主频道 为World，而至少应该说是 Main-world(主世界)。 + + +Node +^^^^ + +Node(节点) 描述 ES 的实现端，这是它们的统一称谓。同时，通过 ES 所规定的 Events 传递的方向，可以扩展称为 1号节点(Node-1)、2号节点(Node-2) 甚至 3号节点(Node-3)...但是一般来说，两个节点已经足够使用了，Events 的传递方向总是由数字小的节点传递到数字大的节点，若 Events 能在节点间的传递过程中完成给定的任务，则这样的节点传递过程被成为一套完整的 pipeline。 + + +Pipeline +^^^^^^^^ + +管线(Pipeline)，或称“流水线”。这个概念可能比较抽象，因此在这里给出一个生动的形容——Pipeline，你土味一点，可翻译成“一条龙服务”；专业一点，叫它“综合解决方案”。 + +总之，一个 pipeline，一定是完整的，但不一定是闭合的。 + +Element +^^^^^^^ + +Element(元素)尤其指代包含在 Events 中的各类可以被抽象出来的概念，比如文本(Text)、图片(Image)、富文本(RichText)、音频(Audio)、视频(Vedio)等。具体可翻阅元素列表 [Elements.md](./Element.md) 查看所有 ES 1.0 定义的元素。 + + +Event +^^^^^ + +Event(事件)只存在于节点之间。事件划分为 Specific-events(具体事件，例如消息事件、世界人数增减事件等) 与 Abstract-events(抽象事件，例如工作流事件、回调事件等)。具体可翻阅事件一览表 [Events.md](./Event.md) 查看所有 ES 1.0 所支持的事件。 + + +API +^^^ + +是指节点(尤其是 Node-2)需要实现的一些网络接口规范。具体参阅 ES 1.0 API列表 `API.md`。 + +.. _API.md: ./API.html diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..40b7e6c --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,79 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys + +if sys.version_info >= (3, 11): + import tomllib +else: + import tomli as tomllib + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "ECHO" +release = "latest" +copyright = "2023-PRESENT, HydroRoll-Team." +author = "HsiangNianian" + +html_title = "ECHO" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.todo", + "sphinx.ext.napoleon", + "sphinx.ext.autosummary", + "sphinx.ext.extlinks", + "myst_parser", +] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +extlinks = { + "issue": ("https://github.com/HydroRoll-Team/echo/%s", "issue %s"), + "doc": ("https://echo.hydroroll.team/zh-cn/latest/%s", "pages/%s"), +} +source_suffix = { + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", +} + +locale_dirs = ["../locales/"] # path is example but recommended. +gettext_compact = False # optional. +gettext_uuid = True # optional. + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["../_static"] +_html_logo = "https://cdn.jsdelivr.net/gh/HydroRoll-Team/echo@main/docs/_static/echo.png" +html_favicon = _html_logo + +html_css_files = [ + "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css", + "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css", +] + +html_theme_options = { + "announcement": "🎉 documentation is still under construction now, welcome any contribution!", + "source_repository": "https://github.com/HydroRoll-Team/echo/", + "source_branch": "main", + "source_directory": "docs/source/", + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/HydroRoll-Team/echo/", + "html": "", + "class": "fa-brands fa-github", + }, + ], +} \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..410375e --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,91 @@ +Echo 规范 +============= + +ES ``1.0.0`` 是 Echo 规范的第一个投入生产环境的版本，而 Echo 是水系规定 HydroRoll 与 infini 以及 HydroRollCore 之间事件传参类型的一个内部标准，全称 Event Communication and Harmonization across Online platforms。 + +一、版本 1.0.0 +^^^^^^^^^^^^^^ + +文档里的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 都遵循 `BCP 14`_ 、 `RFC2119`_ 、 `RFC8174`_ 里的解释说明。 + +.. _BCP 14: https://www.rfc-editor.org/info/bcp14 +.. _RFC2119: https://datatracker.ietf.org/doc/html/rfc2119 +.. _RFC8174: https://datatracker.ietf.org/doc/html/rfc8174 + + +二、介绍 +^^^^^^^^ + +Echo 规范(ES), 是定义一个标准的、与具体编程语言无关的 RESTful API 与 Event Defined 规范。文字跑团(TRPG)游戏是一种基于文字描述和角色扮演的桌上游戏，通常由一个游戏主持人(KP)和多个玩家(PC)组成，通过网络平台进行交流和互动。不同的平台可能有不同的功能和限制，比如群聊、频道、图片、音频甚至视频等，这些都会影响到游戏的体验和效果。为了让水系的文字跑团游戏能够跨平台运行，ES 规定了游戏的数据结构、接口定义、错误处理等。这样，水系用户的 TRPG 游戏就可以在不同的平台上实现相同或相似的功能，同时也可以方便模型或规则包或插件开发者进行扩展和定制。 + + +三、术语定义 +^^^^^^^^^^^ + +3.1 ES 文档 +----------- + +一（或多）份用来定义或描述一个 Event 以及 API 的文档。 + +3.2 Media Types +--------------- + +媒体类型定义分散于多处。 媒体类型定义应当符合 ``RFC6838``。 + +以下是一些媒体类型定义的示例： + +.. code:: + + text/plain; charset=utf-8 + application/json + application/vnd.github+json + application/vnd.github.v3+json + application/vnd.github.v3.raw+json + application/vnd.github.v3.text+json + application/vnd.github.v3.html+json + application/vnd.github.v3.full+json + application/vnd.github.v3.diff + application/vnd.github.v3.patch + + +3.3 HTTP状态码 +-------------- + +HTTP状态码被用来表示一次请求的被执行状态。[RFC7231] 定义了有效的状态码，可以在 [IANA Status Code Registry] 找到已经被注册的状态码的列表。 + +[RFC7231]: http://tools.ietf.org/html/rfc7231#section-6 +[IANA Status Code Registry]: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml + +3.4 其他术语 +------------ + +包含 Window、World、Event、Element等词条, 详见 `Term.md`_。 + +.. _Term.md: ./Term.html + +四、规范 +^^^^^^^^ + +4.1 版本 +-------- + +开放 API 规范使用符合 ``语义化版本 2.0.0`` `semver`_ 规范的版本号。版本号由三部分组成: 主版本号.次版本号.修订号。每次更新文档时，根据以下规则递增版本号： +* 主版本号：当 API 有不兼容的修改时，递增主版本号，例如从 ``1.0.0`` 变为 ``2.0.0``。 +* 次版本号：当 API 有向下兼容的功能新增时，递增次版本号，例如从 ``1.0.0`` 变为 ``1.1.0``。 +* 修订号：当 API 有向下兼容的问题修正时，递增修订号，例如从 ``1.0.0`` 变为 ``1.0.1``。 +支持开放API规范 ``1.0`` 的工具应该兼容所有 ``1.0.*`` 的版本，工具不应当关注修订版本号，比如 ``1.0.0`` 和 ``1.0.1`` 对它来说应该没有任何区别。 + +此后开放 API 规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此 ``1.1.0`` 版本的规范应当可以在面向 1.0.0 版本规范开发的工具内使用。 + +任何兼容开放 API 规范 ``1.*.*`` 的文档应当包含一个 echo 字段用来表明它使用的规范的语义化版本。 + +.. _semver: http://semver.org/spec/v2.0.0.html + + +.. toctree:: + :hidden: + + Term + Element + Event + API \ No newline at end of file -- cgit v1.2.3-70-g09d2