feat(docs): update requirements and docs content with new sphinx extensions and translations

12 files changed, 127 insertions, 35 deletions

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7d74be3..2e616e2 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,4 +4,5 @@ sphinx-autobuild>=2024.4.16
 myst-parser>=3.0.1
 sphinx>=7.3.7
 tomli>=2.0.1
-sphinx-intl>=2.2.0
\ No newline at end of file
+sphinx-intl>=2.2.0
+sphinxcontrib-httpdomain
\ No newline at end of file
diff --git a/docs/source/about/docs_changelog.rst b/docs/source/about/docs_changelog.rst
new file mode 100644
index 0000000..64412b9
--- /dev/null
+++ b/docs/source/about/docs_changelog.rst
@@ -0,0 +1,8 @@
+文档变更日志
+============
+
+文档正在不断完善中。在之后的版本中，本文档将包含所有第一个 release 版本之后的有效变更，包括对类参考手册的更新。
+
+.. note::
+
+    本文档仅包含新页面，因此并未反映所有更改，许多页面已经大幅更新，但未反映在本文档中。
\ No newline at end of file
diff --git a/docs/source/about/index.rst b/docs/source/about/index.rst
index 0bf07f1..6db3b5a 100644
--- a/docs/source/about/index.rst
+++ b/docs/source/about/index.rst
@@ -11,4 +11,4 @@
     complying_with_licenses
     release_policy
     changelog
-
+    docs_changelog
diff --git a/docs/source/about/introduction.rst b/docs/source/about/introduction.rst
index ff01d3d..aebcf94 100644
--- a/docs/source/about/introduction.rst
+++ b/docs/source/about/introduction.rst
@@ -6,14 +6,6 @@
     if: contained!(event.message, r"Hello") => p", World!" ? false;
 
 
-.. code-block:: rust
-
-    fn main() {
-        println!("Hello, world!");
-    }
-
-
-:issue:`23`
 
 在开始之前
 ----------------------------
diff --git a/docs/source/about/list_of_features.rst b/docs/source/about/list_of_features.rst
index 6bfa49f..8bd8315 100644
--- a/docs/source/about/list_of_features.rst
+++ b/docs/source/about/list_of_features.rst
@@ -7,6 +7,7 @@
 顶层业务
 --------
 
+
 规则包机制
 ----------
 
diff --git a/docs/source/about/release_policy.rst b/docs/source/about/release_policy.rst
index 33a60da..fa1505c 100644
--- a/docs/source/about/release_policy.rst
+++ b/docs/source/about/release_policy.rst
@@ -10,6 +10,7 @@ HydroRoll 版本
 新项目应该使用哪个版本？
 ------------------------------------------
 
+
 我应该把项目升级到新版本的水系框架吗？
 ------------------------------------------
 
diff --git a/docs/source/community/code-of-conduct.rst b/docs/source/community/code-of-conduct.rst
index e9da725..5cafc44 100644
--- a/docs/source/community/code-of-conduct.rst
+++ b/docs/source/community/code-of-conduct.rst
@@ -95,15 +95,14 @@
 参见
 ----
 
-本行为准则改编自 [Contributor Covenant][homepage] 2.1 版, 参见 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]。
+本行为准则改编自 `Contributor Covenant`_ 2.1 版, 参见 `Code of Conduct`_。
 
-社区处理方针灵感来源于 [Mozilla's code of conduct enforcement ladder][Mozilla CoC]。
+社区处理方针灵感来源于 `Mozilla's code of conduct enforcement ladder`_。
 
-有关本行为准则的常见问题的答案，参见 [https://www.contributor-covenant.org/faq][FAQ]。
-其他语言翻译参见 [https://www.contributor-covenant.org/translations][translations]。
+有关本行为准则的常见问题的答案，参见 https://www.contributor-covenant.org/faq。
 
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+其他语言翻译参见 https://www.contributor-covenant.org/translations。
+
+.. _Contributor Covenant: https://www.contributor-covenant.org
+.. _Code of Conduct: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+.. _Mozilla's code of conduct enforcement ladder: https://github.com/mozilla/diversity
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4496f04..fa4794e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -10,6 +10,9 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 
+def setup(app):
+    app.add_config_value('releaselevel', '', 'env')
+    
 DATA = None
 PYPROJECT = os.path.join("..", "..", "Cargo.toml")
 with open(PYPROJECT, "r", encoding="utf8") as f:
@@ -35,15 +38,33 @@ author = AUTHORS  # "Hsiang Nianian"
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinx.ext.todo",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.imgmath",
     "sphinx.ext.intersphinx",
+    "sphinxcontrib.httpdomain",
+    "sphinx.ext.ifconfig",
     "myst_parser",
 ]
 
+doctest_global_setup = '''
+try:
+    import hydro_roll as hr
+    import hydro_roll_core as hrc
+except ImportError:
+    hr = None
+    hrc = None
+'''
+todo_include_todos = True
+todo_emit_warnings = True
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -55,6 +76,14 @@ source_suffix = {
     ".txt": "markdown",
     ".md": "markdown",
 }
+rst_prolog = """
+.. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
+
+   .. warning::
+   
+        This stuff is only included in the built docs for unstable versions.
+
+"""
 rst_epilog = """
 .. |psf| replace:: Python Software Foundation
 """
@@ -62,7 +91,7 @@ locale_dirs = ["../locales/"]  # path is example but recommended.
 gettext_compact = False  # optional.
 gettext_uuid = True  # optional.
 numfig = True # Figures, tables and code blocks are automatically numbered if they have a title
-pygments_style = "colorful" # default sphinx, change the style of code block
+pygments_style = "rrt" # default sphinx, change the style of code block
 math_number_all = True # Number all equations, figures, tables and code blocks
 html_additional_pages = {
     'copy': 'copying.html',
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 03adfc7..eb64bdc 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -16,30 +16,24 @@
 
 .. toctree::
     :hidden:
-
+    :caption: Learning
+    
     getting_started/index
-
-
-.. toctree::
-    :hidden:
-
     tutorials/index
-    
-
-.. toctree::
-    :hidden:
-
-    contributing/index
 
 
 .. toctree::
     :hidden:
+    :caption: Community
 
+    contributing/index
     community/index
 
 
 .. toctree::
     :hidden:
-    :caption: 开放 API 手册
+    :caption: Development
 
-    类参考 <api/index.rst>
+    类参考手册 <api/index.rst>
+    restful
+    
diff --git a/docs/source/restful.rst b/docs/source/restful.rst
new file mode 100644
index 0000000..b5c2d5b
--- /dev/null
+++ b/docs/source/restful.rst
@@ -0,0 +1,52 @@
+Restful API 参考手册
+====================
+
+users
+-----
+
+
+.. http:get:: /users/(int:user_id)/posts/(tag)
+
+   The posts tagged with `tag` that the user (`user_id`) wrote.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /users/123/posts/web HTTP/1.1
+      Host: example.com
+      Accept: application/json, text/javascript
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Vary: Accept
+      Content-Type: text/javascript
+
+      [
+        {
+          "post_id": 12345,
+          "author_id": 123,
+          "tags": ["server", "web"],
+          "subject": "I tried Nginx"
+        },
+        {
+          "post_id": 12346,
+          "author_id": 123,
+          "tags": ["html5", "standards", "web"],
+          "subject": "We go to HTML 5"
+        }
+      ]
+
+   :query sort: one of ``hit``, ``created-at``
+   :query offset: offset number. default is 0
+   :query limit: limit number. default is 30
+   :reqheader Accept: the response content type depends on
+                      :mailheader:`Accept` header
+   :reqheader Authorization: optional OAuth token to authenticate
+   :resheader Content-Type: this depends on :mailheader:`Accept`
+                            header of request
+   :statuscode 200: no error
+   :statuscode 404: there's no user
\ No newline at end of file
diff --git a/pdm.lock b/pdm.lock
index 7cf1700..e56db40 100644
--- a/pdm.lock
+++ b/pdm.lock
@@ -5,7 +5,7 @@
 groups = ["default", "dev", "docs", "pygments"]
 strategy = ["cross_platform"]
 lock_version = "4.5.0"
-content_hash = "sha256:73c983e0c428ef724ad782d5a1d6fc97507038bf6fe15c54db85723bca4953de"
+content_hash = "sha256:ff94024bc4f914003e4bedd14669f044799ecadfdbfab59ac08ac94e5431f17c"
 
 [[metadata.targets]]
 requires_python = ">=3.9"
@@ -1878,6 +1878,20 @@ files = [
 ]
 
 [[package]]
+name = "sphinxcontrib-httpdomain"
+version = "1.8.1"
+requires_python = ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*"
+summary = "Sphinx domain for documenting HTTP APIs"
+dependencies = [
+    "Sphinx>=1.6",
+    "six",
+]
+files = [
+    {file = "sphinxcontrib-httpdomain-1.8.1.tar.gz", hash = "sha256:6c2dfe6ca282d75f66df333869bb0ce7331c01b475db6809ff9d107b7cdfe04b"},
+    {file = "sphinxcontrib_httpdomain-1.8.1-py2.py3-none-any.whl", hash = "sha256:21eefe1270e4d9de8d717cc89ee92cc4871b8736774393bafc5e38a6bb77b1d5"},
+]
+
+[[package]]
 name = "sphinxcontrib-jsmath"
 version = "1.0.1"
 requires_python = ">=3.5"
diff --git a/pyproject.toml b/pyproject.toml
index 4a95b57..059b8cb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -64,6 +64,7 @@ docs = [
     "sphinx>=7.3.7",
     "tomli>=2.0.1",
     "sphinx-intl>=2.2.0",
+    "sphinxcontrib-httpdomain>=1.8.1",
 ]
 pygments = [
     "docutils>=0.20.1",