diff options
| -rw-r--r-- | docs/requirements.txt | 3 | ||||
| -rw-r--r-- | docs/source/about/docs_changelog.rst | 8 | ||||
| -rw-r--r-- | docs/source/about/index.rst | 2 | ||||
| -rw-r--r-- | docs/source/about/introduction.rst | 8 | ||||
| -rw-r--r-- | docs/source/about/list_of_features.rst | 1 | ||||
| -rw-r--r-- | docs/source/about/release_policy.rst | 1 | ||||
| -rw-r--r-- | docs/source/community/code-of-conduct.rst | 17 | ||||
| -rw-r--r-- | docs/source/conf.py | 31 | ||||
| -rw-r--r-- | docs/source/index.rst | 22 | ||||
| -rw-r--r-- | docs/source/restful.rst | 52 | ||||
| -rw-r--r-- | pdm.lock | 16 | ||||
| -rw-r--r-- | pyproject.toml | 1 |
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 @@ -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", |