重命名： doc/utils/icon.py -> doc/utils/links.py

doc/_ext/rtd_version.py

@@ -0,0 +1,49 @@
+import os
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    # Define the json_url for our version switcher.
+    json_url = f"https://{app.config.project}.readthedocs.io/zh-cn/latest/_static/switcher.json"
+    # Define the version we use for matching in the version switcher.
+    version_match = os.environ.get("READTHEDOCS_VERSION")
+    # If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+    # If it is an integer, we're in a PR build and the version isn't correct.
+    # If it's "latest" → change to "dev" (that's what we want the switcher to call it)
+    if not version_match or version_match.isdigit() or version_match == "latest":
+        # For local development, infer the version to match from the package.
+        if "dev" in app.config.release or "rc" in app.config.release:
+            version_match = "dev"
+            # We want to keep the relative reference if we are in dev mode
+            # but we want the whole url if we are effectively in a released version
+            json_url = "_static/switcher.json"
+        else:
+            version_match = f"v{app.config.release}"
+    elif version_match == "stable":
+        version_match = f"v{app.config.release}"
+    app.config["html_theme_options"].update({"switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },})
+    # -- To demonstrate ReadTheDocs switcher -------------------------------------
+    # This links a few JS and CSS files that mimic the environment that RTD uses
+    # so that we can test RTD-like behavior. We don't need to run it on RTD and we
+    # don't wanted it loaded in GitHub Actions because it messes up the lighthouse
+    # results.
+    if not os.environ.get("READTHEDOCS") and not os.environ.get("GITHUB_ACTIONS"):
+        app.add_css_file(
+            "https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css"
+        )
+        app.add_css_file("https://assets.readthedocs.org/static/css/badge_only.css")
+
+        # Create the dummy data file so we can link it
+        # ref: https://github.com/readthedocs/readthedocs.org/blob/bc3e147770e5740314a8e8c33fec5d111c850498/readthedocs/core/static-src/core/js/doc-embed/footer.js  # noqa: E501
+        app.add_js_file("rtd-data.js")
+        app.add_js_file(
+            "https://assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js",
+            priority=501,
+        )
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/_static/switcher.json

@@ -7,6 +7,6 @@
   {
     "name": "RTD",
     "version": "latest",
-    "url": "https://pytorch-book.readthedocs.io/zh-cn/"
+    "url": "https://torch-book.readthedocs.io/zh-cn/"
   }
 ]

doc/conf copy.py

@@ -0,0 +1,285 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path('__file__').resolve().parents[1]
+sys.path.extend([str(ROOT/'src'), str(ROOT/"doc"), str(ROOT/'doc/_ext')])
+from utils.icon import icon_links
+# import torch_book
+
+if sys.platform == 'win32':
+    import asyncio
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+# -- Project information -----------------------------------------------------
+
+project = 'torch_book'
+copyright = '2021, xinetzone'
+author = 'xinetzone'
+
+# The full version, including alpha/beta/rc tags
+html_baseurl = 'https://xinetzone.github.io/torch-book'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "myst_nb",
+    # "nbsphinx",  
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx_thebe",
+    "sphinx_copybutton",
+    "sphinx_comments",
+    "sphinxcontrib.mermaid",
+    "matplotlib.sphinxext.plot_directive",
+    "sphinx_plotly_directive",
+    "sphinx_sitemap",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx_automodapi.automodapi",
+    "sphinx_automodapi.smart_resolver",
+    'autoapi.extension',
+    "sphinx.ext.todo",
+    "sphinxcontrib.bibtex",
+    # "sphinx_togglebutton",
+    "sphinx.ext.viewcode",
+    # "sphinx.ext.doctest",
+    "sphinx_design",
+    "sphinx_proof",
+    # "sphinx.ext.ifconfig",
+    # "sphinxext.opengraph",
+    # "sphinx_immaterial",
+    "manim.utils.docbuild.manim_directive",
+    "manim.utils.docbuild.autocolor_directive",
+    "manim.utils.docbuild.autoaliasattr_directive",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+    "amsmath",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+    "html_image",
+    "replacements",
+    "smartquotes",
+    "substitution",
+    "tasklist",
+]
+
+comments_config = {
+    "hypothesis": True,
+    "dokieli": False,
+    "utterances": {
+        "repo": "xinetzone/torch-book",
+        "optional": "config",
+    }
+}
+
+autodoc_default_options = {
+    'autosummary': True,
+}
+
+suppress_warnings = [
+    "mystnb.unknown_mime_type",  # 禁用 application/vnd.plotly.v1+json and application/vnd.bokehjs_load.v0+json 警告
+    "myst.xref_missing", # 禁用 myst 警告
+    "autoapi.python_import_resolution", "autoapi.not_readable" # 禁用 autoapi 警告
+    "sphinx_automodapi.automodapi",
+    "autosectionlabel.*", "autosummary", "intersphinx.external",
+    "autodoc", "autodoc.import_object"
+]
+
+# extlinks = {
+#     # 'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
+#     #           'restructuredtext.html#%s', ''),
+#     # 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/'
+#     #            'roles.html#%s', ''),
+#     # 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/'
+#     #           'directives.html#%s', ''),
+#     # 'daobook': ('https://daobook.github.io/%s', ''),
+# }
+
+intersphinx_mapping = {
+    'python': ('https://daobook.github.io/cpython/', None),
+    'sphinx': ('https://daobook.github.io/sphinx/', None),
+    'peps': ('https://daobook.github.io/peps', None),
+    "pytorch": ("https://pytorch.org/docs/stable", None),
+    "torchvision": ("https://pytorch.org/vision/stable", None),
+    "ultralytics": ("https://docs.ultralytics.com/zh", None),
+    "mmengine": ("https://mmengine.readthedocs.io/zh-cn/latest", None),
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'zh_CN'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_book_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+html_css_files = ["default.css"]
+
+# -- 国际化输出 ----------------------------------------------------------------
+
+locale_dirs = ['locales/']  # path is example but recommended.
+gettext_compact = False  # optional.
+
+# -- 主题设置 -------------------------------------------------------------------
+
+# 定制主侧栏
+html_sidebars = {
+    "*": [
+        "search-field.html",
+        "sbt-sidebar-nav.html",
+    ],
+    "posts/**": [
+        "postcard.html",
+        "recentposts.html",
+        "tagcloud.html",
+        "categories.html",
+        "archives.html",
+        "searchbox.html",
+    ],
+}
+
+todo_include_todos = True
+
+# -- Options for autosummary/autodoc output ------------------------------------
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_member_order = "groupwise"
+
+# -- Options for autoapi -------------------------------------------------------
+autoapi_type = "python"
+autoapi_dirs = ["../src/torch_book"]
+autoapi_keep_files = False # 要开始自己编写 API 文档，你可以让 AutoAPI 保留其生成的文件作为基础
+autoapi_root = "api"
+autoapi_member_order = "groupwise"
+
+# ``pydata-sphinx-theme`` 配置
+# Define the json_url for our version switcher.
+json_url = 'https://xinetzone.github.io/torch-book/_static/switcher.json'
+# -- Sitemap -----------------------------------------------------------------
+# ReadTheDocs has its own way of generating sitemaps, etc.
+if not os.environ.get("READTHEDOCS"):
+    extensions += ["sphinx_sitemap"]
+    html_baseurl = os.environ.get("SITEMAP_URL_BASE", "http://127.0.0.1:8000/")
+    sitemap_locales = [None]
+    sitemap_url_scheme = "{link}"
+# Define the version we use for matching in the version switcher.
+version_match = os.environ.get("READTHEDOCS_VERSION")
+
+html_theme_options = {
+    # -- 如果你的文档只有一个页面，而且你不需要左边的导航栏，那么 ---------------
+    # 你可以在 单页模式 下运行，
+    # "single_page": False,  # 默认 `False`
+    "github_url": "https://github.com/xinetzone/torch-book",
+    # 默认情况下，编辑按钮将指向版本库的根。
+    # 如果你的文档被托管在一个子文件夹中，请使用以下配置：
+    "path_to_docs": "doc/",  # 文档的路径，默认 `docs/``
+    "repository_url": "https://github.com/xinetzone/torch-book",
+    "repository_branch": "main",  # 文档库的分支，默认 `master`
+    # -- 在导航栏添加一个按钮，链接到版本库的议题 ------------------------------
+    # （与 `repository_url` 和 `repository_branch` 一起使用）
+    # -- 在导航栏添加一个按钮，以下载页面的源文件。
+    # "use_download_button": True,  # 默认 `True`
+    # 你可以在每个页面添加一个按钮，允许用户直接编辑页面文本，
+    # 并提交拉动请求以更新文档。
+    "use_edit_page_button": True,
+    # 在导航栏添加一个按钮来切换全屏的模式。
+    # "use_fullscreen_button": True,  # 默认 `True`
+    # -- 在导航栏中添加一个链接到文档库的按钮。----------------------------------
+    # "use_repository_button": True,  # 默认 `False`
+    # -- 包含从 Jupyter 笔记本建立页面的 Binder 启动按钮。 ---------------------
+    # "launch_buttons": '', # 默认 `False`
+    "home_page_in_toc": False,  # 是否将主页放在导航栏（顶部）
+    # -- 只显示标识，不显示 `html_title`，如果它存在的话。-----
+    # -- 在导航栏中显示子目录，向下到这里列出的深度。 ----
+    # "show_navbar_depth": 2,
+    # -- 在侧边栏页脚添加额外的 HTML -------------------
+    # （如果 `sbt-sidebar-footer.html `在 `html_sidebars` 中被使用）。
+    # "extra_navbar": extra_navbar,
+    # -- 在每个页面的页脚添加额外的 HTML。---
+    # "extra_footer": '',
+    # （仅限开发人员）触发一些功能，使开发主题更容易。
+    # "theme_dev_mode": False
+    # 重命名页内目录名称
+    # "toc_title": "导航",
+    "launch_buttons": {
+        # https://mybinder.org/v2/gh/xinetzone/torch_book/main
+        "binderhub_url": "https://mybinder.org",
+        # "jupyterhub_url": "https://datahub.berkeley.edu",  # For testing
+        "colab_url": "https://colab.research.google.com/",
+        # 你可以控制有人点击启动按钮时打开的界面。
+        "notebook_interface": "jupyterlab",
+        "thebe": True,  # Thebe 实时代码单元格,
+        "deepnote_url": "https://deepnote.com",
+    },
+    # 图标可以参考 https://fontawesome.com/icons
+    "icon_links": icon_links,
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
+    "footer_start": ["version-switcher", "copyright"],
+    "footer_end": ["sphinx-version", "last-updated"],
+}
+# -- 自定义网站的标志 --------------
+html_logo = 'logo.jpg'
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = "page-logo.jfif"
+
+# -- 自定义网站的标题 --------------
+# html_title = '动手学习 Python'
+
+# 如果你希望stderr和stdout中的每个输出都被合并成一个流，请使用以下配置。
+# 避免将 jupter 执行报错的信息输出到 cmd
+nb_merge_streams = True
+nb_execution_allow_errors = True
+nb_execution_mode = "off" # "off"
+# nbsphinx_assume_equations = False
+nb_execution_excludepatterns = []
+
+bibtex_bibfiles = ["refs.bib"]
+# To test that style looks good with common bibtex config
+bibtex_reference_style = "author_year"
+graphviz_output_format = 'svg'
+
+numfig = True
+todo_include_todos = True
+navigation_with_keys = True