开发工具【免费下载链接】jupyterJupyter metapackage for installation and documentation项目地址https://gitcode.com/gh_mirrors/ju/jupyter点击查看免费下载Jupyter 项目本仓库即其安装与文档元包为社区贡献者维护了一套完整的文档写作与构建工具链。本文以 doc-tools.rst 为核心系统讲解 Jupyter 文档团队使用的核心工具Sphinx 与 swagger、三类源文件格式、主题选型并结合本仓库真实的构建配置conf.py、Makefile、doc-requirements.txt展开源码级佐证。读完本文你将掌握 Jupyter 文档项目从选择工具到本地构建验证的完整路径以及新贡献者上手 git 与 GitHub 的推荐学习资源。文档工具篇在整体贡献指南中的位置本仓库的文档贡献体系由 docs-contributions/index.rst 汇总其中doc-tools.rst与getting-started.rst准备工作与首次贡献流程、doc-workflow.rst高层文档工作流并列专门回答我们用什么工具写文档这一问题。按 getting-started.rst 的概述Jupyter 文档体系的技术底座可以概括为四点文档源文件使用 reStructuredText、Markdown 与 Jupyter notebook 三种格式使用 Sphinx 作为主构建引擎使用 Transifex 将文档翻译为多语言文档托管于 Read the Docs 平台。doc-tools.rst正是围绕第一、第二点给出更细的工具清单本文以下各节即沿其原始脉络展开。核心工具选型Sphinx 与 swagger用户文档Sphinx对于用户文档、贡献者指南与社区沟通内容Jupyter 官方统一采用Sphinx。Sphinx 是从 docutils 演化而来的 Python 文档构建系统它负责把分散的.rst/.md源文件解析、组织并渲染成 HTML 等最终产物。本仓库是这一选型的直接实践样本文档构建配置集中在 docs/source/conf.py其中声明了source_suffix [.rst, .md]支持两类文本源格式、master_doc index主目录文件以及一整套扩展。需要特别指出的是当前仓库实际启用的扩展比文档篇描述的传统组合更为现代化包括sphinx.ext.autodoc从 Python 源码 docstring 自动抽取 API 文档sphinx.ext.doctest执行文档中嵌入的 doctest 代码块sphinx.ext.intersphinx跨项目链接到其他 Sphinx 文档sphinx.ext.graphviz渲染 Graphviz 图形graphviz_output_format svgsphinxext.rediraffe管理文档重定向本仓库用它把content-quickstart.rst、tryjupyter.rst重定向到start/index.mdmyst_parser支持 MarkdownMyST语法sphinx_design提供网格卡片等页面组件。其中intersphinx的映射通过intersphinx_registry生成覆盖 ipython、nbconvert、nbformat、ipywidgets、traitlets、ipyparallel、notebook、qtconsole、hub、lab 等 Jupyter 生态项目见 conf.py说明各 Jupyter 子项目的文档可以互相引用彼此的对象与页面形成一张互联的文档网络。开发者 API 文档swagger当需要为开发者生成 API 接口文档时——尤其是 JupyterLab 的 JavaScript 仓库——Jupyter 选用swaggerOpenAPI 生态的工具集来描述和呈现 HTTP API。这与 Sphinx 形成互补Sphinx 长于叙事性、结构化的用户文档而 swagger 更适合面向机器的接口契约与可交互的 API 调试界面。依赖清单的仓库实证在 doc-requirements.txt 中可以查到本文档站点构建所依赖的完整包清单sphinx3.1 sphinx-intl myst_parser nbsphinx pydata-sphinx-theme sphinxext-rediraffe sphinx-design intersphinx_registry其中nbsphinx负责把.ipynbnotebook 直接纳入 Sphinx 构建印证了Notebook 也是源文件格式的说法sphinx-intl服务于多语言翻译对应locale/目录下的.po文件pydata-sphinx-theme是当前实际采用的 HTML 主题。支持的源文件格式.rst、.md 与 .ipynbdoc-tools.rst明确列出 Jupyter 文档开发使用的三类输入源文件格式这也是本仓库docs/source目录下真实存在的三种文件形态格式扩展名典型用途仓库实例reStructuredText.rst结构化长文档、目录树、交叉引用本页正文 doc-tools.rst、doc-workflow.rst、doc-future-index.rstMarkdown.md轻量文档、列表式页面index.md、what_is_jupyter.md、repo-structure.mdNotebook.ipynb可交互、可执行的教程由nbsphinx在构建时执行并渲染从源码结构看.rst是 Sphinx 生态的原生格式支持.. toctree::目录树、:ref:交叉引用等强结构能力因此文档指南类内容如本文所在的 contributing 目录几乎全部使用.rstMarkdown 则凭借更低的书写门槛用于首页、快速导览等场景notebook 适合需要边跑代码边讲解的教学内容。三者通过conf.py中的source_suffix [.rst, .md]与nbsphinx扩展在同一构建中统一处理。doc-tools.rst还提醒编写源文件应当使用现代代码编辑器例如 Atom、SublimeText、gedit、vim、emacs并特别推荐 Atom 作为新贡献者的入门选择编辑器提供的语法高亮、RST 实时预览与 Git 集成能显著降低格式错误的概率。Sphinx 主题选型不同 Jupyter 子项目在 HTML 主题上有两种主流选择sphinx_rtd_themeRead the Docs 风格主题目前 Jupyter 各项目普遍采用jupyter_sphinx_themeipywidgets 项目采用的 Jupyter 定制主题。而本仓库当前的实际构建conf.py已演进为pydata_sphinx_themePyData 社区主题并配套配置了html_logo _static/_images/jupyter.svg、html_favicon _static/_images/favicon.png、暗色 Logo_static/_images/logo-rectangle-dark.svg、编辑按钮use_edit_page_button以及指向 Jupyter 生态的导航链接。这说明主题选型是随项目演进动态调整的贡献者在为本仓库写文档时以 conf.py 中html_theme的实际取值为准即可。主题相关的静态资源统一放在docs/source/_static/目录图片、图标、自定义 CSS其中 custom.css 与 jupyter.css 会在 Sphinx 的setup()钩子中通过app.add_css_file()注入见 conf.py。从工具到实践本仓库的文档目录结构与构建流程理解了工具选型后可对照本仓库的 repo-structure.md 理解文档目录的组织规范仓库根目录下的docs目录存放全部文档源文件docs/source目录存放.rst、.md、.ipynb内容源文件docs/Makefile与docs/make.bat提供跨平台构建入口docs/environment.yml提供 conda 构建环境conf.py是 Sphinx 配置index.rst是主目录文件_static放图片与图标build是构建产物目录不应提交到版本库。本仓库文档构建依赖的 conda 环境定义在 environment.yml固定使用python3.11并经由 pip 安装doc-requirements.txt中的全部依赖name: jupyter_docs dependencies: - python3.11 - pip: - -r doc-requirements.txt从 docs/Makefile 可以看到完整的构建目标其中最常用的包括make html构建本地 HTML 版本产物输出到docs/build/html浏览器打开build/html/index.html即可预览make linkcheck校验文档中所有外部链接是否仍然有效make doctest执行文档内嵌的 doctest 代码块make gettext生成用于翻译的 PO 消息目录make clean清空构建产物。上述流程与 getting-started.rst 中的测试建议完全一致从docs目录执行make html与make linkcheck是提交文档改动前的最低验证门槛。完成本地验证后即可按照 doc-workflow.rst 的八步流程识别改动 → 更新源文件 → 提交 → 本地测试 → 开 Pull Request → 检查自动化测试 → 等待评审合并 → 继续贡献提交贡献。Git 与 GitHub 学习资源对于第一次接触 GitHub 或 git 的新贡献者doc-tools.rst建议按需学习以下资源均为社区公认的入门材料Try Git交互式在线练习适合零基础快速建立 git 基本操作手感GitHub GuidesGitHub 官方使用指南覆盖仓库、分支、Issue、Pull Request 等核心概念Git RealCodeSchool 出品的 git 视频课程偏实战演练Git Documentationgit 官方文档作为命令与概念的权威参考Git Rebasepandas 项目维基整理的 git 工作流与 rebase 操作说明有助于理解开源协作中保持提交历史整洁的做法。这些资源与 doc-workflow.rst、github_workflow.rst 共同构成新贡献者从会写文档到会协作的完整学习路径。小结一套文档项目的最小技术栈综合doc-tools.rst与本仓库实际配置Jupyter 文档项目的最小技术栈可以归纳为构建引擎Sphinx负责将.rst/.md/.ipynb统一渲染为 HTMLAPI 文档swagger面向 JupyterLab 等 JS 仓库的开发者接口文档格式reStructuredText结构化主文档、Markdown轻量页面、Notebook可执行教程主题sphinx_rtd_theme / jupyter_sphinx_theme本仓库当前为 pydata_sphinx_theme构建入口docs/Makefile与docs/source/conf.py依赖见docs/doc-requirements.txt与docs/environment.yml协作工具git 与 GitHub配套上文列出的学习资源。对照 doc-tools.rst、getting-started.rst 与 doc-workflow.rst 三份文档新贡献者可以快速走通选对工具 → 本地构建 → 提交验证的完整链路为 Jupyter 文档持续注入高质量的改进。赞分享开发工具【免费下载链接】jupyterJupyter metapackage for installation and documentation项目地址https://gitcode.com/gh_mirrors/ju/jupyter点击查看免费下载相关推荐Jupyter 文档本地构建实战基于 Sphinx 从源码生成官方文档站点Jupyter 文档本地构建实战基于 Sphinx 从源码生成官方文档站点 导读本指南以 Jupyter metapackage 仓库 README.fr开发工具pypdf 文档工程实践指南Sphinx 构建、doctest 代码校验与文档协作规范pypdf 文档工程实践指南Sphinx 构建、doctest 代码校验与文档协作规范 pypdf 是一个纯 Python 实现的 PDF 处理库其官方文档后端DeepChem 文档构建与测试实战基于 Sphinx 的本地文档工作流指南DeepChem 文档构建与测试实战基于 Sphinx 的本地文档工作流指南 DeepChem 项目主打Democratizing Deep Learni人工智能深度学习机器学习生物信息学科学计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考