docs

发表于 更新于 分类于 本文字数： 5.2k 阅读时长 ≈ 5 分钟

mkdocs

MkDocs 是一个用于创建漂亮的静态文档网站的工具

links:

quickstart

以下是一些快速开始的步骤:

1
2
3
4
5
6
7
8
# 安装依赖
pip install mkdocs
# 在本地创建文档配置
mkdocs new .
# 预览 serve 在mkdocs.yml中的文档
mkdocs serve
# 构建 public 静态文件,可用于CI部署
mkdocs build --site-dir public

page navigation

在 MkDocs 中，可以使用 mkdocs.yml 配置文件来定义导航栏的结构和顺序。以下是一些常用的导航栏配置选项：

  • nav：nav 是一个列表，用于定义导航栏的各个部分。每个部分都表示为一个字典，包含 title 和 url 字段。例如：

1
2
3
4
nav:
  - Home: index.md
  - About: about.md
  - Contact: contact.md

在上面的示例中，导航栏将包含 "Home"、"About" 和 "Contact" 三个部分，分别链接到 index.md、about.md 和 contact.md 文件。

  • pages：如果文档结构比较复杂，可以使用 pages 字段来定义更详细的导航栏结构。pages 是一个列表，每个列表项表示一个页面，可以是一个 Markdown 文件或一个包含 title 和 url 字段的字典。例如：

1
2
3
4
5
6
pages:
  - Home: index.md
  - About:
      - Introduction: about/intro.md
      - Team: about/team.md
  - Contact: contact.md

在上面的示例中，导航栏将包含 "Home"、"About" 和 "Contact" 三个部分。"About" 部分下面有两个子页面：“Introduction"和"Team”，分别链接到 about/intro.md 和 about/team.md 文件。

  • theme.nav：如果正在使用特定主题（如 Material 主题），某些主题可能提供了额外的导航栏配置选项。可以在 mkdocs.yml 中的 theme 部分下找到这些选项。例如，在 Material 主题中，可以使用 theme.nav 字段来定义导航栏。例如：

1
2
3
4
5
6
theme:
  name: material
  nav:
    - Home: index.md
    - About: about.md
    - Contact: contact.md

material theme

MkDocs Material 主题基于 Google 的 Material Design 风格，提供了现代化和响应式的用户界面。它的设计简洁、易于阅读，并且提供了一些有用的功能，如侧边栏导航、搜索功能、代码高亮等。

以下是一些 MkDocs Material 主题的特点：

  • 响应式布局：MkDocs Material 主题会自动适应不同的屏幕大小和设备类型，使文档在桌面、平板和手机上都能良好地显示。

  • 侧边栏导航：MkDocs Material 主题提供了一个侧边栏导航菜单，方便用户浏览和导航文档的不同部分。

  • 搜索功能：MkDocs Material 主题集成了强大的搜索功能，使用户能够快速找到所需的文档内容。

  • 代码高亮：MkDocs Material 主题使用了 Prism.js 库来实现代码高亮，支持多种编程语言和主题。

  • 自定义配置：可以通过修改 MkDocs 的配置文件来自定义 MkDocs Material 主题的外观和行为，包括颜色、字体、导航栏等。

links:

color

作为任何恰当的 Material Design 实现，Material for MkDocs 支持 Google 的原始调色板，可以通过 MkDocs.yml 轻松配置。此外，通过使用 CSS 变量，可以通过几行 CSS 来定制颜色，以适应品牌标识。

links:

language

MkDocs 的 Material 支持国际化 (i18n) ，并提供 60 多种语言的模板变量和标签的翻译。此外，如果可用的话，可以将站点搜索配置为使用特定于语言的词干分析器。

links:

versions with mike

通过与外部实用程序集成，将这些功能添加到 MkDocs，即 Mike，MkDocs 的 Material 使得部署项目文档的多个版本变得非常容易。在部署新版本时，文档的旧版本保持不变。

links:

项目文档的页脚是一个很好的地方，可以添加链接到或公司正在使用的网站或平台作为额外的营销渠道，例如，或者，可以通过 mkdocs.yml 轻松配置。

  • 禁用显示文档生成脚标，即不再显示 Made with Material for MkDocs

links:

markdown extensions

MkDocs 的 Material 支持大量的 Python Markdown 扩展，这是它对于技术写作如此有吸引力的部分原因。下面是所有支持的扩展的列表，链接到引用的相关部分，这些部分需要启用这些特性。

links:

plugins

links:

mkdocs-same-dir

通常 mkdocs 不允许将 docs_dir 配置为 mkdocs.yml 所在路径，但这也导致 无法引用 项目根目录的 markdown.md 文件。mkdocs-same-dir 为了解决这个问题，允许将 docs_dir 设置为 mkdocs.yml 路径，即 docs_dir: ..

使用该插件后，需要对 mkdocs.yml 相应路径适配 docs_dir: . 配置。其中包括如下:

links:

mkdocs-jupyter

安装依赖

1
pip install mkdocs-jupyter

配置 plugin

1
2
3
4
5
6
7
nav:
  - Home: index.md
  - Notebook page: notebook.ipynb
  - Python file: python_script.py

plugins:
  - mkdocs-jupyter

links:

mkdocstrings

Python 处理程序使用 Griffe 从 Python 源代码中收集文档。在法语中，“Griffe” 这个词有时可以用来代替 “签名”。Griffe 可以访问源代码的抽象语法树 (AST) 来提取有用的信息。当源代码不可用时，它还可以执行代码 (通过导入) 和内省内存中的对象。最后，它可以按照不同的样式解析文档字符串。

links:

mkdocs-coveage

MkDocs 插件将覆盖率 HTML 报告集成到站点中。通过分析 coverage report html 导出在 htmlcov 文件夹并加载到 coverage.md 页面上.

links:

mkdoxy

MkDocs 的 MkDoxy 插件根据 Doxygen 注释和 markdown 文件中的代码片段生成 API 文档。

links:

integrate with ci

发布到远程仓库，并自动部署依赖于代码管理平台，通常使用命令生成静态站点文件到 public 目录，然后由代码管理平台部署。如果使用 mike 发布，请参考 mike 相关内容

links:

sphinx

Sphinx 是一个用于文档生成的工具。它可以帮助将标记语言（如 reStructuredText）编写的文档转换为各种格式，如 HTML、PDF、EPUB 等。Sphinx 是 Python 社区中最常用的文档生成工具之一，被广泛用于编写 Python 项目的文档。

使用 Sphinx 编写文档非常简单。只需要在项目中创建一个配置文件（通常是 conf.py），指定文档源文件的位置以及输出格式的配置。然后，可以使用 reStructuredText 编写文档内容，使用 Sphinx 提供的命令将其转换为所需的格式。

Sphinx 还提供了丰富的功能，如自动生成 API 文档、跨引用、索引、主题定制等。可以根据需要选择适合项目的功能。

links:

who use sphinx:

Versioning

links: