后端微服务【免费下载链接】jupyterhubMulti-user server for Jupyter notebooks项目地址https://gitcode.com/gh_mirrors/ju/jupyterhub点击查看免费下载本文基于 JupyterHub 仓库中的贡献者文档页docs/source/contributing/docs.md展开讲清楚 JupyterHub 文档的完整技术栈——Sphinx 构建、MyST 格式源码、docs/source目录结构——并给出在本地复现官方文档站的两套构建方式nox一键实时预览、Makefile/sphinx-build手动构建以及仓库实际使用的配置细节。读完后你可以独立在本地搭建文档构建环境、修改并验证文档渲染效果并遵循项目既定的书写约定。文档技术栈Sphinx 构建 MyST 源码JupyterHub 的文档用 Sphinx 构建。文档源码以 MySTMarkedly Structured Text格式编写统一存放在docs/source目录下再由 Sphinx 转换为人可读的多种输出格式。这一结构可以从三处源码直接印证docs/source/index.md 是文档根页conf.py 中设置了root_doc indexsource_suffix [.md]表明整个文档站只接受 MarkdownMyST源文件不混用 reST 源文件但default_role literal保留了 reST 中单反引号表示行内代码的习惯写法docs/source/conf.py 中的myst_heading_anchors 2会为 H1/H2 标题自动生成锚点myst_enable_extensions额外开启了attrs_inline、colon_fence、deflist、fieldlist、substitution等 MyST 扩展语法如{ref}、{class}角色和:::{note}围栏。构建扩展一览从 conf.py 的extensions列表看文档构建依赖以下扩展其安装由 docs/requirements.txt 统一声明扩展 / 依赖作用sphinx.ext.autodoc从 Python 源码自动生成 API 文档见docs/source/reference/api/各页sphinx.ext.intersphinx跨项目引用外部 API 文档python、tornado、jupyter-server、nbgitpuller、aiohttpsphinx.ext.napoleon解析 Google/NumPy 风格 docstringautodoc_traitsautodoc-traits自动文档化 JupyterHub 基于 traitlets 的配置属性sphinx_copybutton为代码块添加复制按钮sphinx-jsonschema渲染 REST API 的 JSON Schema 内容sphinxext.opengraph生成社交分享用的 OpenGraph 元数据sphinxext.rediraffe文档移动/改名后的自动重定向防止链接失效jupyterhub_sphinx_themeJupyter 统一风格主题myst_parser0.19解析 MyST 语法docs/requirements.txt 中还有一个值得注意的约定文件头注释明确说明文档构建要求 jupyterhub 本身已安装但不在这里声明该依赖因为这往往会导致重复安装构建工具版本约束为sphinx4,9低版本 Python 下通过tomli兜底解析pyproject.toml。本地构建文档官方建议在你撰写或修改的文档合入前先在本地构建并验证渲染结果。前提是系统已安装 Python 和 Git开发环境完整要求见 开发环境搭建指南从pyproject.toml看当前项目要求 Python 3.10而文档中的{{python_min}}/{{node_min}}占位符正是由 conf.py 从该值与硬编码值动态替换而来。方式一用nox构建并实时预览仓库使用nox命令行工具统一管理文档构建。核心命令是nox -s docs -- live这一条命令会安装文档依赖、构建文档并启动一个带实时刷新的预览服务器。其背后逻辑全部体现在 noxfile.py 的docs会话中nox.session(defaultFalse) def docs(session): Build the documentation and, optionally with -- live, run a web server. docs_dir docs source_dir os.path.join(docs_dir, source) # where conf.py is located data_dir os.path.join(source_dir, _data) output_dir os.path.join(docs_dir, _build) session.install(--editable, .) session.install(-r, os.path.join(docs_dir, requirements.txt)) doc_build_default_args [-b, dirhtml, source_dir, output_dir] if live in session.posargs: # For live preview, sphinx-autobuild is used. ... session.install(sphinx-autobuild) cmd [sphinx-autobuild] autobuild_ignore [output_dir, os.path.join(data_dir, generated)] for folder in autobuild_ignore: cmd.extend([--ignore, f*/{folder}/*]) cmd.extend(doc_build_default_args) session.run(*cmd) else: session.run(sphinx-build, *doc_build_default_args)从源码结构看nox -s docs会话做了四件事以可编辑模式安装 JupyterHub 本体再安装docs/requirements.txt固定使用dirhtml构建器输出目录为docs/_build追加-- live参数时额外安装sphinx-autobuild并启动监视器保存.md文件即自动重建刷新实时模式会把docs/_build输出目录和docs/source/_data/generated加入忽略清单--ignore避免构建产物变化反过来触发无限重建。此外nox.options.reuse_existing_virtualenvs True使 nox 复用已创建的虚拟环境二次构建不必重复安装依赖。不传live参数时nox -s docs行为等同于直接执行sphinx-build -b dirhtml docs/source docs/_build。方式二不用nox手动构建不依赖 nox 时先在仓库根目录安装文档所需包python3 -m pip install --editable . python3 -m pip install -r docs/requirements.txt然后有两种构建入口。入口 Asphinx-build直接构建。安装完成后即可运行与 nox 会话相同的底层命令python3 -m sphinx -b html docs/source docs/_build/html入口 Bdocs/下的 Makefile。docs/Makefile 是 sphinx-quickstart 生成的标准 Makefile并加入了本项目自定义目标。关键配置SPHINXOPTS ? --color -W --keep-going SPHINXBUILD ? sphinx-build SOURCEDIR source BUILDDIR _build注意SPHINXOPTS中的-W --keep-going-W把文档构建中的警告提升为错误因此任何失效的链接、拼写问题若启用拼写检查都会让构建失败——这就是 JupyterHub 文档保持零警告纪律的机制来源。Makefile 的目标分两类通用目标%: Makefile捕获规则任意未显式定义的目标都转发给sphinx-build -M 目标例如make html、make clean、make linkcheck全站外链检查、make spelling拼写检查自定义目标html: metrics $(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) ... metrics: source/includes/metrics_table.md source/includes/metrics_table.md: python3 generate-metrics.pymake html依赖metrics目标它先运行 docs/generate-metrics.py 生成指标文档页所需的source/includes/metrics_table.md再执行 Sphinx 构建。docs/Makefile 中还定义了devenv目标——在make html之上启动sphinx-autobuild -b html --open-browser自动打开浏览器并在文件变化时热重建适合长时间写作。从源码结构看Makefile 与 conf.py 之间存在一条隐藏依赖链conf.py 中有一段 Read The Docs 适配代码if os.environ.get(READTHEDOCS): subprocess.check_call([make, metrics, scopes], cwdstr(docs))即云端构建RTD 直接跑sphinx-build而不经过make html会由 conf.py 手动补跑make metrics和make scopes后者对应 docs/source/rbac/generate-scope-table.py 生成 RBAC scope 表格。Makefile 注释也提醒若修改了html目标的前置步骤必须同步更新 conf.py 中的这段 RTD 代码否则本地构建与云端构建行为会分叉。文档站的关键配置机制以下机制虽然不在贡献者文档页中展开但直接影响文档作者需要知道的行为均出自 docs/source/conf.py。自定义指令让文档内容与代码版本保持同步conf.py 定义并注册了三个 Sphinx 自定义指令app.add_directive(...)它们在实际构建时调用 JupyterHub 代码动态生成内容避免手写文档与代码漂移jupyterhub-generate-configConfigDirective实例化JupyterHub()后调用generate_config_file()把当前版本的完整配置文件生成内容嵌入文档用于 配置参考页并把输出中的$HOME路径脱敏jupyterhub-help-allHelpAllDirective捕获--help-all的完整输出作为代码块嵌入文档jupyterhub-rest-api-linksRestAPILinksDirective解析 docs/source/_static/rest-api.yml为每个 REST 操作的operationId生成可被{ref}引用的锚点供文档正文精确链接到 Redoc 渲染的 API 文档。文档重定向rediraffe为避免移动文档后旧链接 404项目启用了sphinxext.rediraffe。conf.py 中的配置为rediraffe_branch os.environ.get(REDIRAFFE_BRANCH, main) rediraffe_redirects redirects.txt rediraffe_auto_redirect_perc 80重定向记录全部集中在 docs/source/redirects.txt例如changelog.md reference/changelog.md、admin/upgrading.md howto/upgrading.md文件末尾还留有 add future redirects below 的维护提示。conf.py 注释中给出了三种添加重定向的工作流手动维护redirects.txt、make rediraffecheckdiff分析差异后人工补充或make rediraffewritediff自动写入自动识别阈值为 80% 相似。外链检查与拼写检查linkcheck_ignore列表conf.py 第 304 行起列出了linkcheck目标跳过的一批正则GitHub 锚点、changelog 中大量 PR 链接、example.com示例链接、localhost 等减少误报噪音拼写检查是可选扩展conf.py 用try: import sphinxcontrib.spelling探测安装后才启用词表为 docs/source/spelling_wordlist.txt。文档相关的质量校验测试docs/test_docs.py 用 pytest 对文档产物做两项硬校验是文档正确性的自动化防线test_rest_api_version_is_updated断言 jupyterhub/_version.py 中的__version__与rest-api.yml中info.version完全一致防止 REST API 定义文件版本滞后test_rest_api_rbac_scope_descriptions_are_updated重新执行 docs/source/rbac/generate-scope-table.py然后用git diff --exit-code确认rest-api.yml中 RBAC scope 描述与生成结果零差异即该文件不允许出现手改漂移。文档书写约定Documentation conventions贡献者文档页将约定声明为一份持续生长的活文档并欢迎社区补充修订。当前已确立的明确约定如下。pip调用方式调用pip有多种写法JupyterHub 文档中统一推荐python3 -m pip这样能显式地使用你当前正在用的python3可执行文件对应的 pip是最不容易出问题的调用方式因为它几乎不会遇到python3与pip来自不同环境的错配例如系统pip指向 Python 2或 venv 未激活时误装到别处。项目自身文档也一贯遵守该约定例如上文给出的安装命令均写作python3 -m pip install --editable .。其他可观察到的隐性约定结合docs/source的实际用法以下惯例在现有文档中普遍存在修改文档时保持一致即可源码文件统一为.mdMyST标题锚点由myst_heading_anchors 2生成页内引用使用 MyST 角色如{ref}、{class}而非手写锚点目录组织按迪克森Diátaxis风格分为tutorial/、howto/、explanation/、reference/、faq/、contributing/六类见 docs/source/index.md构建警告视为错误-W新文档应确保零警告、通过make linkcheck与拼写检查。小结贡献 JupyterHub 文档的完整本地工作流为按 开发环境搭建指南 装好 Python 与 Git → 执行nox -s docs -- live启动实时预览或python3 -m pip install --editable . python3 -m pip install -r docs/requirements.txt后走 docs/Makefile /sphinx-build→ 在docs/source下用 MyST 编写、遵守python3 -m pip等书写约定 → 依赖-W严格构建、make linkcheck/make spelling与 docs/test_docs.py 的自动化校验保证质量。核心源码文件为 docs/source/conf.py构建配置、noxfile.py构建自动化与 docs/Makefile构建入口三处均可作为进一步深入文档构建机制的入口。赞分享后端微服务【免费下载链接】jupyterhubMulti-user server for Jupyter notebooks项目地址https://gitcode.com/gh_mirrors/ju/jupyterhub点击查看免费下载相关推荐PyPTO 文档贡献实战指南写作规范、目录注册与 Sphinx 本地构建全流程PyPTO 文档贡献实战指南写作规范、目录注册与 Sphinx 本地构建全流程 PyPTOParallel Tensor/Tile Operation是人工智能编译器模型编译深度学习高性能计算CANNAscendpython-guide 文档贡献指南Sphinx 构建、本地预览与写作风格规范全解析python guide 文档贡献指南Sphinx 构建、本地预览与写作风格规范全解析 导读 本文基于 CONTRIBUTING.md https://lin文档教程Cutter 文档贡献指南Sphinx 文档体系、写作方向与本地构建全流程Cutter 文档贡献指南Sphinx 文档体系、写作方向与本地构建全流程 Cutter基于 Rizin 的开源逆向工程平台的官方文档长期面临内容不完善的应用安全桌面应用开发工具上一篇xrdp网络诊断命令集从客户端到服务器下一篇GitHub Stats Visualization模板定制教程如何自定义SVG图表样式和布局创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 JupyterHub 文档贡献指南：Sphinx + MyST 本地构建、nox 工作流与书写规范
后端微服务【免费下载链接】jupyterhubMulti-user server for Jupyter notebooks项目地址https://gitcode.com/gh_mirrors/ju/jupyterhub点击查看免费下载本文基于 JupyterHub 仓库中的贡献者文档页docs/source/contributing/docs.md展开讲清楚 JupyterHub 文档的完整技术栈——Sphinx 构建、MyST 格式源码、docs/source目录结构——并给出在本地复现官方文档站的两套构建方式nox一键实时预览、Makefile/sphinx-build手动构建以及仓库实际使用的配置细节。读完后你可以独立在本地搭建文档构建环境、修改并验证文档渲染效果并遵循项目既定的书写约定。文档技术栈Sphinx 构建 MyST 源码JupyterHub 的文档用 Sphinx 构建。文档源码以 MySTMarkedly Structured Text格式编写统一存放在docs/source目录下再由 Sphinx 转换为人可读的多种输出格式。这一结构可以从三处源码直接印证docs/source/index.md 是文档根页conf.py 中设置了root_doc indexsource_suffix [.md]表明整个文档站只接受 MarkdownMyST源文件不混用 reST 源文件但default_role literal保留了 reST 中单反引号表示行内代码的习惯写法docs/source/conf.py 中的myst_heading_anchors 2会为 H1/H2 标题自动生成锚点myst_enable_extensions额外开启了attrs_inline、colon_fence、deflist、fieldlist、substitution等 MyST 扩展语法如{ref}、{class}角色和:::{note}围栏。构建扩展一览从 conf.py 的extensions列表看文档构建依赖以下扩展其安装由 docs/requirements.txt 统一声明扩展 / 依赖作用sphinx.ext.autodoc从 Python 源码自动生成 API 文档见docs/source/reference/api/各页sphinx.ext.intersphinx跨项目引用外部 API 文档python、tornado、jupyter-server、nbgitpuller、aiohttpsphinx.ext.napoleon解析 Google/NumPy 风格 docstringautodoc_traitsautodoc-traits自动文档化 JupyterHub 基于 traitlets 的配置属性sphinx_copybutton为代码块添加复制按钮sphinx-jsonschema渲染 REST API 的 JSON Schema 内容sphinxext.opengraph生成社交分享用的 OpenGraph 元数据sphinxext.rediraffe文档移动/改名后的自动重定向防止链接失效jupyterhub_sphinx_themeJupyter 统一风格主题myst_parser0.19解析 MyST 语法docs/requirements.txt 中还有一个值得注意的约定文件头注释明确说明文档构建要求 jupyterhub 本身已安装但不在这里声明该依赖因为这往往会导致重复安装构建工具版本约束为sphinx4,9低版本 Python 下通过tomli兜底解析pyproject.toml。本地构建文档官方建议在你撰写或修改的文档合入前先在本地构建并验证渲染结果。前提是系统已安装 Python 和 Git开发环境完整要求见 开发环境搭建指南从pyproject.toml看当前项目要求 Python 3.10而文档中的{{python_min}}/{{node_min}}占位符正是由 conf.py 从该值与硬编码值动态替换而来。方式一用nox构建并实时预览仓库使用nox命令行工具统一管理文档构建。核心命令是nox -s docs -- live这一条命令会安装文档依赖、构建文档并启动一个带实时刷新的预览服务器。其背后逻辑全部体现在 noxfile.py 的docs会话中nox.session(defaultFalse) def docs(session): Build the documentation and, optionally with -- live, run a web server. docs_dir docs source_dir os.path.join(docs_dir, source) # where conf.py is located data_dir os.path.join(source_dir, _data) output_dir os.path.join(docs_dir, _build) session.install(--editable, .) session.install(-r, os.path.join(docs_dir, requirements.txt)) doc_build_default_args [-b, dirhtml, source_dir, output_dir] if live in session.posargs: # For live preview, sphinx-autobuild is used. ... session.install(sphinx-autobuild) cmd [sphinx-autobuild] autobuild_ignore [output_dir, os.path.join(data_dir, generated)] for folder in autobuild_ignore: cmd.extend([--ignore, f*/{folder}/*]) cmd.extend(doc_build_default_args) session.run(*cmd) else: session.run(sphinx-build, *doc_build_default_args)从源码结构看nox -s docs会话做了四件事以可编辑模式安装 JupyterHub 本体再安装docs/requirements.txt固定使用dirhtml构建器输出目录为docs/_build追加-- live参数时额外安装sphinx-autobuild并启动监视器保存.md文件即自动重建刷新实时模式会把docs/_build输出目录和docs/source/_data/generated加入忽略清单--ignore避免构建产物变化反过来触发无限重建。此外nox.options.reuse_existing_virtualenvs True使 nox 复用已创建的虚拟环境二次构建不必重复安装依赖。不传live参数时nox -s docs行为等同于直接执行sphinx-build -b dirhtml docs/source docs/_build。方式二不用nox手动构建不依赖 nox 时先在仓库根目录安装文档所需包python3 -m pip install --editable . python3 -m pip install -r docs/requirements.txt然后有两种构建入口。入口 Asphinx-build直接构建。安装完成后即可运行与 nox 会话相同的底层命令python3 -m sphinx -b html docs/source docs/_build/html入口 Bdocs/下的 Makefile。docs/Makefile 是 sphinx-quickstart 生成的标准 Makefile并加入了本项目自定义目标。关键配置SPHINXOPTS ? --color -W --keep-going SPHINXBUILD ? sphinx-build SOURCEDIR source BUILDDIR _build注意SPHINXOPTS中的-W --keep-going-W把文档构建中的警告提升为错误因此任何失效的链接、拼写问题若启用拼写检查都会让构建失败——这就是 JupyterHub 文档保持零警告纪律的机制来源。Makefile 的目标分两类通用目标%: Makefile捕获规则任意未显式定义的目标都转发给sphinx-build -M 目标例如make html、make clean、make linkcheck全站外链检查、make spelling拼写检查自定义目标html: metrics $(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) ... metrics: source/includes/metrics_table.md source/includes/metrics_table.md: python3 generate-metrics.pymake html依赖metrics目标它先运行 docs/generate-metrics.py 生成指标文档页所需的source/includes/metrics_table.md再执行 Sphinx 构建。docs/Makefile 中还定义了devenv目标——在make html之上启动sphinx-autobuild -b html --open-browser自动打开浏览器并在文件变化时热重建适合长时间写作。从源码结构看Makefile 与 conf.py 之间存在一条隐藏依赖链conf.py 中有一段 Read The Docs 适配代码if os.environ.get(READTHEDOCS): subprocess.check_call([make, metrics, scopes], cwdstr(docs))即云端构建RTD 直接跑sphinx-build而不经过make html会由 conf.py 手动补跑make metrics和make scopes后者对应 docs/source/rbac/generate-scope-table.py 生成 RBAC scope 表格。Makefile 注释也提醒若修改了html目标的前置步骤必须同步更新 conf.py 中的这段 RTD 代码否则本地构建与云端构建行为会分叉。文档站的关键配置机制以下机制虽然不在贡献者文档页中展开但直接影响文档作者需要知道的行为均出自 docs/source/conf.py。自定义指令让文档内容与代码版本保持同步conf.py 定义并注册了三个 Sphinx 自定义指令app.add_directive(...)它们在实际构建时调用 JupyterHub 代码动态生成内容避免手写文档与代码漂移jupyterhub-generate-configConfigDirective实例化JupyterHub()后调用generate_config_file()把当前版本的完整配置文件生成内容嵌入文档用于 配置参考页并把输出中的$HOME路径脱敏jupyterhub-help-allHelpAllDirective捕获--help-all的完整输出作为代码块嵌入文档jupyterhub-rest-api-linksRestAPILinksDirective解析 docs/source/_static/rest-api.yml为每个 REST 操作的operationId生成可被{ref}引用的锚点供文档正文精确链接到 Redoc 渲染的 API 文档。文档重定向rediraffe为避免移动文档后旧链接 404项目启用了sphinxext.rediraffe。conf.py 中的配置为rediraffe_branch os.environ.get(REDIRAFFE_BRANCH, main) rediraffe_redirects redirects.txt rediraffe_auto_redirect_perc 80重定向记录全部集中在 docs/source/redirects.txt例如changelog.md reference/changelog.md、admin/upgrading.md howto/upgrading.md文件末尾还留有 add future redirects below 的维护提示。conf.py 注释中给出了三种添加重定向的工作流手动维护redirects.txt、make rediraffecheckdiff分析差异后人工补充或make rediraffewritediff自动写入自动识别阈值为 80% 相似。外链检查与拼写检查linkcheck_ignore列表conf.py 第 304 行起列出了linkcheck目标跳过的一批正则GitHub 锚点、changelog 中大量 PR 链接、example.com示例链接、localhost 等减少误报噪音拼写检查是可选扩展conf.py 用try: import sphinxcontrib.spelling探测安装后才启用词表为 docs/source/spelling_wordlist.txt。文档相关的质量校验测试docs/test_docs.py 用 pytest 对文档产物做两项硬校验是文档正确性的自动化防线test_rest_api_version_is_updated断言 jupyterhub/_version.py 中的__version__与rest-api.yml中info.version完全一致防止 REST API 定义文件版本滞后test_rest_api_rbac_scope_descriptions_are_updated重新执行 docs/source/rbac/generate-scope-table.py然后用git diff --exit-code确认rest-api.yml中 RBAC scope 描述与生成结果零差异即该文件不允许出现手改漂移。文档书写约定Documentation conventions贡献者文档页将约定声明为一份持续生长的活文档并欢迎社区补充修订。当前已确立的明确约定如下。pip调用方式调用pip有多种写法JupyterHub 文档中统一推荐python3 -m pip这样能显式地使用你当前正在用的python3可执行文件对应的 pip是最不容易出问题的调用方式因为它几乎不会遇到python3与pip来自不同环境的错配例如系统pip指向 Python 2或 venv 未激活时误装到别处。项目自身文档也一贯遵守该约定例如上文给出的安装命令均写作python3 -m pip install --editable .。其他可观察到的隐性约定结合docs/source的实际用法以下惯例在现有文档中普遍存在修改文档时保持一致即可源码文件统一为.mdMyST标题锚点由myst_heading_anchors 2生成页内引用使用 MyST 角色如{ref}、{class}而非手写锚点目录组织按迪克森Diátaxis风格分为tutorial/、howto/、explanation/、reference/、faq/、contributing/六类见 docs/source/index.md构建警告视为错误-W新文档应确保零警告、通过make linkcheck与拼写检查。小结贡献 JupyterHub 文档的完整本地工作流为按 开发环境搭建指南 装好 Python 与 Git → 执行nox -s docs -- live启动实时预览或python3 -m pip install --editable . python3 -m pip install -r docs/requirements.txt后走 docs/Makefile /sphinx-build→ 在docs/source下用 MyST 编写、遵守python3 -m pip等书写约定 → 依赖-W严格构建、make linkcheck/make spelling与 docs/test_docs.py 的自动化校验保证质量。核心源码文件为 docs/source/conf.py构建配置、noxfile.py构建自动化与 docs/Makefile构建入口三处均可作为进一步深入文档构建机制的入口。赞分享后端微服务【免费下载链接】jupyterhubMulti-user server for Jupyter notebooks项目地址https://gitcode.com/gh_mirrors/ju/jupyterhub点击查看免费下载相关推荐PyPTO 文档贡献实战指南写作规范、目录注册与 Sphinx 本地构建全流程PyPTO 文档贡献实战指南写作规范、目录注册与 Sphinx 本地构建全流程 PyPTOParallel Tensor/Tile Operation是人工智能编译器模型编译深度学习高性能计算CANNAscendpython-guide 文档贡献指南Sphinx 构建、本地预览与写作风格规范全解析python guide 文档贡献指南Sphinx 构建、本地预览与写作风格规范全解析 导读 本文基于 CONTRIBUTING.md https://lin文档教程Cutter 文档贡献指南Sphinx 文档体系、写作方向与本地构建全流程Cutter 文档贡献指南Sphinx 文档体系、写作方向与本地构建全流程 Cutter基于 Rizin 的开源逆向工程平台的官方文档长期面临内容不完善的应用安全桌面应用开发工具上一篇xrdp网络诊断命令集从客户端到服务器下一篇GitHub Stats Visualization模板定制教程如何自定义SVG图表样式和布局创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考