什么是狮身人面像?
- 一个功能强大的工具,可帮助您格式化文档。
- 使用reStructuredText或Markdown编写文档。
- 它可以输出为HTML,PDF,ePub等。
眼见为实。例如,您可以使用以下图像创建一个手动站点。这是一种广泛使用的工具,因此您可能会看到类似的图像。 ..
本文将向您展示如何构建以下示例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
-
Markdown支持如下所述。
为此验证创建的文档结构
我想创建一个具有以下结构的文档。
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 |
为此验证创建的文件夹结构
当多个人一起工作时,您想将文件分成多个部分,对吗?
让我们创建一个三样式的文件夹结构,同时更改文件划分的粒度。
图像如下。
创建文档文件。
结构结构定义在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 |
以下是
文件关系的直观表示。
文件内容
手册\\源\\ 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 ####. |
完成的文档图像
第1部分(Part-01)使用一个index.md文件创建了整个文档。
在这种情况下,面包屑列表似乎表示为一层。
屏幕顶部中央的" ??"