My Dev Config
Sphinx¶
Why sphinx¶
之前一直纠结了很久的文档生成器。包括 核心的文档语言包括
markdown
rst
mdx
org
tex
很显然如果想要简单，选用markdown即可。但是markdown的功能收到限制，因此需要进一步扩展起能力，就得往下。 而mdx虽然很好，交互丰富，但是想来还是使用python更多，因此，最后还是选择了rst. 不过还有包括 [MyST] 这种有趣的md扩展。
Install 常用的sphinx扩展¶
常用的设置
我的吐槽
最烦的就是默认功能不开启，需要额外安装，等你想用的时候，查文档才能知道是安装的时候某个功能没有启用。 而且有些功能居然需要你重新编译，这种设置还不如不开启。。。 这里需要注意的就是，你使用的myst-parser,需要开启的插件功能需要安装 linkify-it-py 。
myst_enable_extensions = [
"amsmath",
"attrs_inline",
"colon_fence",
"deflist",
"dollarmath",
"fieldlist",
"html_admonition",
"html_image",
"linkify",
"replacements",
"smartquotes",
"strikethrough",
"substitution",
"tasklist",
]
pip install myst-parser[linkify] \
sphinxcontrib-mermaid \
sphinx_design \
sphinx-copybutton \
sphinxcontrib-bibtex\
sphinx-comments \
sphinxemoji
extensions=[
"myst_parser",
"sphinx_design",
"sphinx_copybutton",
"sphinxcontrib.bibtex",
"sphinx_comments",
"sphinxcontrib.mermaid",
"sphinxemoji.sphinxemoji",
]
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
]
bibtex_bibfiles = ['refs.bib']
MyST-Parser¶
为了支持直接写markdown, 可以引入这个包.
更多的信息查看这个文档. myst-parser
sphinxcontrib-mermaid¶
由于在 MyST-Parser 介绍了关于这个 mermaid, 感觉非常好用。
更多的文档，请查看 https://mermaid.js.org/intro/
例如，生成一个简单的pie图
.. mermaid::
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
而且这个sphinx的扩展包也支持主题配置，有点6的，具体使用就是在原始的文档中的代码前面加上 .. mermaid::的directive就可以了
例如,代码如下：
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#BB2528',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#F8B229',
'secondaryColor': '#006100',
'tertiaryColor': '#fff'
}
}
}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#BB2528',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#F8B229',
'secondaryColor': '#006100',
'tertiaryColor': '#fff'
}
}
}%%
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
B --> G[/Another/]
C ==>|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
subgraph section
C
D
E
F
G
end
sphinx_design¶
sphinx_design 包括grid，card, dropdown, tab, badegs。
Tabs using sphinx_design¶
.. tab-set::
.. tab-item:: MacOS
:sync: key1
MacOS
.. tab-item:: linux
:sync: key2
linux
.. tab-item:: windows
:sync: key3
windows
macos
linux
windows
Tabs using sphinx_tabs (Abandon)¶
备注
由于sphinx_desin可以实现tab，因此这个extension的可用性比较低，就可以不用了。
.. tabs::
.. tab:: MacOS
MacOS
.. tab:: Linux
Linux
.. tab:: Windows
Windows
Drop using sphinx_design¶
.. dropdown:: Dropdown title
Dropdown content
Dropdown title
Dropdown content
Card using sphinx_design¶
.. card:: Card Title
Header
^^^
Card content
+++
Footer
Header
Card content
Grid using sphinx design¶
.. grid:: 2
:gutter: 2 2 2 2
.. grid-item-card::
A
.. grid-item-card::
B
A
B
sphinx_emoji¶
当然，我也如同 vim-snippets，实现了一个类似的版本，可以查询当前的emoji.
sphinx comments¶
因为这个代码是挂载在 sections = document.querySelectorAll("div.section");. 因此在需要评论的下方，加一个
.. raw::html
<div class="section" />
就可以启用这个插件了。
Sphinx with Latex¶
首先，由于文档很多时候是包括中文的，因此选用 xelatex而不是 pdflatex。然后倒入 ctex.
最简单的设置如下:
latex_engine = 'xelatex'
latex_elements = {
'preamble': r'''
\addto\captionsenglish{\renewcommand{\chaptername}{}}
\usepackage[UTF8, scheme = plain]{ctex}
''',
}
然后使用 make latexpdf
修改为单个页面的pdf¶
关于定制化单个页面，如何实现latex的有效编译，需要查看手册: Latex customization
例如:
latex_engine = 'xelatex'
latex_elements = {
'passoptionstopackages': r'''
\PassOptionsToPackage{svgnames}{xcolor}
''',
'pointsize': '12pt',
'fontpkg': r'''
\setmainfont{Georgia}
''',
'maketitle': r'''
\date{Fall 2024}
\maketitle
''',
'tableofcontents': "",
'preamble': r'''
\usepackage{xeCJK}
\usepackage{hyperref}
\usepackage{url}
\raggedbottom % 避免章节之间产生多余的空白页
\setlength{\parskip}{5pt} % 段落之间空格
''',
'sphinxsetup': r'''
TitleColor=DarkGoldenrod
''',
'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'
latex_documents = [
('project1/index', 'project1.tex', 'Title 1', 'Author 1', 'howto'),
]
latex_additional_files = ["iclr2024_conference.sty"]
特别需要指出的，如果改成了 howto那么对应的是 article类。
如果是默认的会是 Manual。
多个配置文件对于不同的页面¶
例如，我们的某个教学项目，包括教程、练习题和代码手册等。
但是上述的单个页面的 conf.py比较难满足这种需求，因为tex的预加载可能存在差异。
这个时候最好的方式便是分不同的 conf.py, 然后进行处理。
例如，我们可以创建一个 confs/projects/conf.py
然后使用 make latexpdf的时候指定配置文件
make latexpdf SPHINXOPTS="-c ./confs/projects"
Interesting links for sphinx extensions¶
Groups for sphinx¶
[sympy] : 这个是当时找 math + dollar 发现的 github,