feat(docs): update requirements and docs content with new sphinx exte…

…nsions and translations
HydroRoll-Team · Oct 5, 2024 · 4c8caa6 · 4c8caa6
1 parent e614fd9
commit 4c8caa6
Show file tree

Hide file tree

Showing 12 changed files with 127 additions and 35 deletions.
diff --git 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
+sphinx-intl>=2.2.0
+sphinxcontrib-httpdomain
diff --git a/docs/source/about/docs_changelog.rst b/docs/source/about/docs_changelog.rst
@@ -0,0 +1,8 @@
+文档变更日志
+============
+
+文档正在不断完善中。在之后的版本中，本文档将包含所有第一个 release 版本之后的有效变更，包括对类参考手册的更新。
+
+.. note::
+
+    本文档仅包含新页面，因此并未反映所有更改，许多页面已经大幅更新，但未反映在本文档中。
diff --git 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
@@ -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
@@ -7,6 +7,7 @@
 顶层业务
 --------
 
+
 规则包机制
 ----------
 

diff --git 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
@@ -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
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,6 +10,9 @@
 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 @@
 
 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,14 +76,22 @@
     ".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
 """
 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
@@ -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
@@ -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
diff --git a/pdm.lock b/pdm.lock
diff --git 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",
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,6 +7,7 @@ @@
     顶层业务
     --------
     规则包机制
     ----------
@@ Expand Down @@