使用Markdown准备手动创建环境(Sphinx sphinx_rtd_theme推荐标记版)


什么是狮身人面像？

  • 一个功能强大的工具，可帮助您格式化文档。
  • 使用reStructuredText或Markdown编写文档。
  • 它可以输出为HTML，PDF，ePub等。

眼见为实。例如，您可以使用以下图像创建一个手动站点。这是一种广泛使用的工具，因此您可能会看到类似的图像。 ..

part00-index.png

本文将向您展示如何构建以下示例markdown并将其转换为HTML。
https://github.com/ka2taka/lab_202009_sphinx/tree/master/source

构建并输出的HTML如下。
https://ka2taka.github.io/lab_202009_sphinx/part01/index.html

本文假定的工作环境

  • 环境

    • Windows 10专业版
    • Python v3.8.3(Anaconda3)
    • 狮身人面像v3.2.1
    • 推荐标记v0.6.0
    • sphinx-rtd-theme v0.5.0(阅读Docs Sphinx主题)
  • 工作文件夹

    • C：\\工作\\手册

创建Python虚拟环境(virtual env)

1
2
3
4
(base) C:\work>mkdir manual
(base) C:\work\manual>cd manual
(base) C:\work\manual>python -m venv venv
(base) C:\work\manual>venv\Scripts\activate.bat

检查已安装的软件包。

1
2
3
4
5
6
7
(venv) (base) C:\work\manual>pip list
Package    Version
---------- -------
pip        19.2.3
setuptools 41.2.0
WARNING: You are using pip version 19.2.3, however version 20.2.3 is available.
You should consider upgrading via the 'python -m pip install --upgrade pip' command.

我收到警告，所以我升级了PIP

1
2
3
(venv) (base) C:\work\manual>python -m pip install --upgrade pip
...途中省略...
Successfully installed pip-20.2.3
  • 参考

    • 创建虚拟环境

介绍一个Python包。

1
2
3
4
5
6
(venv) (base) C:\work\manual>pip install sphinx
(venv) (base) C:\work\manual>pip install recommonmark
(venv) (base) C:\work\manual>pip install sphinx-markdown-tables
(venv) (base) C:\work\manual>pip install sphinx_rtd_theme
(venv) (base) C:\work\manual>pip install sphinxcontrib-blockdiag
(venv) (base) C:\work\manual>pip install sphinxcontrib-actdiag

狮身人面像设置

1
2
3
4
5
6
7
8
9
10
(venv) (base) C:\work\manual>sphinx-quickstart  
...途中省略...
> Separate source and build directories (y/n) [n]: y
...途中省略...
> Project name: manual
> Author name(s): ka2taka
> Project release []: 2020-12-31
...途中省略...
> Project language [en]: ja
...途中省略...

将创建以下文件夹和文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
(venv) (base) C:\work\manual>tree /F
C:.(manualの場所)
│make.bat
│Makefile
│
├─build　???変換後の文書の出力先。
└─source　???作成する原文の場所。
    │conf.py　???各種設定。
    │index.rst　???ルートになるドキュメント。
    │
    ├─_static
    └─_templates

※venvフォルダ等は記載省略

启用扩展

启用以下功能。

  • 允许从降价转换。
  • 使降价表可用。

  • 启用"阅读文档"主题。

  • 由于我们正在测试UML绘图，因此请启用blockdiag和actdiag。

编辑源代码/ conf.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
extensions = [
    'recommonmark',
    'sphinx_markdown_tables'
    'sphinxcontrib.blockdiag',
    'sphinxcontrib.actdiag',
]
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

from recommonmark.transform import AutoStructify
# github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            # 'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)
1
html_theme = 'sphinx_rtd_theme'
  • 我没有尝试过url_resolver，所以将其注释掉
  • 参考

    • Markdown支持如下所述。

      • https://www.sphinx-doc.org/ja/1.6/markdown.html#markdown
      • https://recommonmark.readthedocs.io/en/latest/auto_structify.html
    • 主题选项如下所述。

      • https://www.sphinx-doc.org/ja/master/usage/theming.html

      • https://planset-study-sphinx.readthedocs.io/ja/latest/06.html
    • 如何编写conf.py

      • https://www.sphinx-doc.org/ja/1.6/config.html

为此验证创建的文档结构

我想创建一个具有以下结构的文档。

1
2
3
4
1. 第1部
  1.1 第1章
    1.1.1 第1節
      1.1.1.1 第1小節

与上面的第1部分类似，我们还将制作第2部分和第3部分。
稍后描述的测试示例文档具有以下英语表达。
没有特别的理由说英语。那只是我一开始做的示例。

1
2
3
4
1. Part-01
  1.1. Chapter-01
    1.1.1. Section-001
      1.1.1.1. Sub Section-001

为此验证创建的文件夹结构

当多个人一起工作时，您想将文件分成多个部分，对吗？
让我们创建一个三样式的文件夹结构，同时更改文件划分的粒度。

图像如下。

slide1.png

创建文档文件。

结构结构定义在reStructuredText中描述。
文本本身是用Markdown编写的。

文件结构说明

在

index.rst中定义它。
在" toctree"下，写入目录的深度以及到文档的链接。

1
2
3
4
5
6
7
8
.. toctree::
   :maxdepth: 3
   :caption: Contents:
   :numbered:

   part01/index ???第1部(Part-01)の文書の場所を指定。
   part02/index ???第2部(Part-02)の文書の場所を指定。
   part03/index ???第3部(Part-03)の文書の場所を指定。

文本主体的描述

文本用Markdown编写。
例如，part01 / index.md是适用的。这是正常的降价。

1
2
3
4
5
# Part-01
Above line is writed by using headers #.

## Chapter-01
Above line is writed by using headers ##.

我将解释如何从此处构建。
首先，尝试使用示例文件进行构建。
该示例在下面，因此将其保存在源代码下。
https://github.com/ka2taka/lab_202009_sphinx

文档文件转换

" make html"将转换文档。
"源"下的文档将在"内部"下转换。

1
2
3
4
5
6
7
(venv) (base) C:\work\manual>make html
Running Sphinx v3.2.1
...(途中省略)...
writing output... [100%] part03/index
C:\work\manual\source\appendix.md:27: WARNING: Pygments lexer name 'markdown' is not known
...(途中省略)...
The HTML pages are in build\html.

似乎无法解释代码块中描述的关键字" markdown"，并发出了警告。关键字" python"似乎是可以解释的。
↓已成为Markdown代码块的描述示例警告

1
2
3
4
5
6
7
```markdown
|a|b|c|
|-----|-----|-----|
|1|2|3|
|a|b|c|
|あ|い|う|
```

有关如何创建文档文件

的说明

在上面，

用于创建文档文件

第1部分的说明(Prat-01)

文件结构定义

手册\\源\\ index.rst
在此示例中，index.rst定义了基础结构。
从根文件夹中的index.rst指定第1部分(Part-01)的位置的描述如下。
maxdepth指示目录的深度。

1
2
3
4
5
6
7
8
9
10
11
sphinx sample document　???　ドキュメント全体のタイトル
======================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:
   :numbered:

   part01/index ???第1部(Part-01)の文書の場所を指定。
   part02/index
   part03/index

以下是

文件关系的直观表示。
slide2.png

文件内容

手册\\源\\ part01 \\ index.md
index.md的内容是正常的markdown。

  • 1级标题"#"是零件的标题。
  • 2级标题" ##"将是本章的标题。
1
2
3
4
5
6
7
8
9
10
11
# Part-01
Above line is writed by using headers #.

## Chapter-01
Above line is writed by using headers ##.

### Section-001
Above line is writed by using headers ###.

#### Sub-Section-001
Above line is writed by using headers ####.

完成的文档图像

part01.png

第1部分(Part-01)使用一个index.md文件创建了整个文档。
在这种情况下，面包屑列表似乎表示为一层。
屏幕顶部中央的" ??"