学习参考资料

Build Your Python Project Documentation With MkDocs – Real Python

配置环境

>>> mkdir settlementCalculation
>>> cd settlementCalculation

>>> pipenv install
>>> pipenv shell
>>> vim .\Pipfile # pip 换源： https://pypi.tuna.tsinghua.edu.cn/simple
>>> git init

>>> New-Item -Path .\settlementCalculation\__init__.py -Type File

>>>git status

安装需要的packages

>>> pipenv install mkdocs
>>> pipenv install "mkdocstrings[python]"
>>> pipenv install mkdocs-material

>>> pipenv graph
>>> pip list

工程目录结构 project structure

>>> mkdocs new .

>>> mkdocs serve

│ mkdocs.yml
│ Pipfile
│ Pipfile.lock
│
├───docs
│ index.md
│
└───settlementCalculation
init.py

Adapt my project settings file

edit mkdocs.yml

site_name: 地基处理沉降计算

theme:
name: "material"

用Markdown 创建静态页面

Create static pages from markdown

Setting up a new MkDocs project creates a default index.md page in docs/. The index page is the default entry point for your project documentation, and you can edit the text in this file to fit your project landing page. You can also add more Markdown files to the docs/ folder, and each of them will render into a new page of your documentation.

As you learned in the project overview, you’ll follow the structure proposed in the Diátaxis documentation framework, which suggests splitting your documentation into four distinct parts

>>> cd docs
>>> "explanation.md, how-to-guides.md, reference.md, tutorials.md" -split ", " |
%{
touch $_
}

• docs/tutorials.md
• docs/how-to-guides.md
• docs/reference.md
• docs/explanation.md

Mkdocs 把 docs/ 目录下的每一个文件生成一个页面。主页面（第一个）是来自 index.md。
余下的页面按照在docs/目录的顺序出现。

文件默认按照字母表顺序排序，当然你也许希望按照Diátaxis 框架建议的顺序进行排序。

为了定制文档页面顺序，需要添加一个nva 元素到settings file 并按照想要的顺序列出所有的文件。

我可以在文件名签名添加一个想要显示的标题，默认标题为.md文件的第一个title.

MkDocs builds every Markdown file that it finds in docs/ as a separate page. The first page that shows up is always index.md. All remaining pages show up in the order listed in docs/.

Files are listed alphabetically by default, but you’d like to preserve the order proposed by the Diátaxis documentation framework.

To determine a custom order for your documentation pages, you need to add the nav element to your settings file and list all files in the order in which you want to show them:

You might have noticed that each page already has a title, which MkDocs inferred from the filenames. If you don’t like a page’s title, you can optionally add another element in front of the filename whose title you want to change:

site_name: 地基处理沉降计算

theme:
  name: "material"

nav:
  - 沉降计算: index.md
  - 使用说明: explanation.md
  - how-to-guides.md
  - 参考: reference.md
  - tutorials.md

从Docstrings 导出文档需要的信息 Insert Information From Docstrings

保持文档的实时性是一项具有挑战性的工作，所有自动生成文档至少部分自动生成是需要，可以实现省时省力的效果。

我仅使用Mkdocs 不能从源码中获取docstrings 。我需要利用另外一个叫 mkdocstrings 的package.

我已经在前面安装了 mkdocstrings, 现在只需要添加到 MkDocs 的配置文件 mkdocs.yml.

Keeping documentation up to date can be challenging, so auto-generating at least parts of your project documentation can save you time and effort.

MkDocs is a static-site generator geared toward writing documentation. However, you can’t fetch docstring information from your code using MkDocs alone. You can make it work with an additional package called mkdocstrings.

You already installed mkdocstrings into your virtual environment at the beginning of this tutorial, so you only need to add it as a plugin to your MkDocs configuration file:

# mkdocs.yml
...
plugins:
  - mkdocstrings
...

在mkdocs.yml 配置文件内写入mkdocstrings , 我就激活了mkdocstrings 这个插件。
Mkdocstrings 允许我把doctrings 插入到Markdown 页面，只需要采用三个冒号(:::)的句法，(:::) 后面跟着想要document的模块或函数的identifier。

By recording mkdocstrings as a list item to the plugins element, you activated the plugin for this project.

Mkdocstrings allows you to insert docstring information right into your Markdown pages using a special syntax of three colons (:::) followed by the code identifier that you want to document:

# reference.md
::: settlementCalculation.main

用MkDocs 生成我们文档

Build Your Documentation With MkDocs

目前为止，我已经完成了所有的文件结构和文档信息的编写（生成）。
最后，我可以生成文档并发布到线上。

At this point, you should’ve written all your documentation pages and the project structure file. At the end of this step, you’ll have built your documentation and be ready to deploy it online.

>>> mkdocs build

上面的命令会生成下面的文件结构：

───site
├───assets
│ ├───images
│ ├───javascripts
│ │ ├───lunr
│ │ │ └───min
│ │ └───workers
│ └───stylesheets
├───explanation
├───how-to-guides
├───reference
└───tutorials