Sphinx¶

Why sphinx¶

之前一直纠结了很久的文档生成器。包括核心的文档语言包括

markdown
rst
mdx
org
tex

很显然如果想要简单，选用markdown即可。但是markdown的功能收到限制，因此需要进一步扩展起能力，就得往下。而mdx虽然很好，交互丰富，但是想来还是使用python更多，因此，最后还是选择了rst. 不过还有包括 [MyST] 这种有趣的md扩展。

Install 常用的sphinx扩展¶

常用的设置

pip install myst-parser \
            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¶

Sphinx Design Tabs

.. tab-set::

    .. tab-item:: MacOS
        :sync: key1

        MacOS

    .. tab-item:: linux
        :sync: key2

        linux

    .. tab-item:: windows
        :sync: key3

        windows

Macos

macos

linux

windows

Tabs using sphinx_tabs¶

Sphinx Tab 文档

MacOS

.. tabs::

   .. tab:: MacOS

     MacOS

   .. tab:: Linux

     Linux

   .. tab::  Windows

        Windows

Drop using sphinx_design¶

Sphinx Design Drop

.. dropdown:: Dropdown title

    Dropdown content

Card using sphinx_design¶

Sphinx Design Card

.. card:: Card Title

    Header
    ^^^
    Card content
    +++
    Footer

Header

Card Title

Card content

Footer

Grid using sphinx design¶

Sphinx Design Grid

.. grid:: 2
    :gutter: 2 2 2 2

    .. grid-item-card::

        A

    .. grid-item-card::

        B

Badges, Button, Icons using sphinx_design¶

Sphinx Design BBI

Inline icon roles are available for the GitHub octicon, Google Material Design Icons, or FontAwesome libraries.

octicon: :octicon:`logo-github;1em;sd-text-info`
Google Material Design: :material-outlined:`g_translate`
FontAwesome: :fab:`fa-brands fa-github-alt`

plain badge

primary, primary-line

secondary, secondary-line

success, success-line

info, info-line

warning, warning-line

danger, danger-line

light, light-line

dark, dark-line

https://hotchilipowder.github.io

Button text

https://hotchilipowder.github.io

sphinx_copybutton¶

Sphinx CopyButton 将会让代码可以被copy

sphinx_emoji¶

Sphinx Emoji

当然，我也如同 vim-snippets，实现了一个类似的版本，可以查询当前的emoji.

sphinx comments¶

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}
''',
}