sphinx快速教程#

1. 创建项目#

1.1. create python venv#

python3 -m venv venv
source venv/bin/activate

1.2. install sphinx#

pip install sphinx

1.3. create project#

sphinx-quickstart [project_name]

1.4. build#

cd project_name
make html

1.5. deploy#

cp -r build/html/*  /path/to/deploy/dir

2. 自定义主题#

2.1. install theme#

pip install sphinx_rtd_theme
pip install pydata_sphinx_theme
pip install sphinx_book_theme
pip install sphinx_press_theme

2.2. enable theme#

vi conf.py
html_theme = "pydata_sphinx_theme"
#html_theme = 'alabaster'
#html_theme = 'sphinx_rtd_theme'
#html_theme = 'press'
#html_theme = 'sphinx_book_theme'
#html_theme = 'furo'

3. markdown support#

pip install myst-parser

vi conf.py
extensions = ['myst_parser']

3.1. myst markdown useful extensions Latex support#

dollarmath amsmath

myst_enable_extensions = [
    "amsmath",
    "attrs_inline",
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
   # "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]

3.2 markdown tabs support#

pip install sphinx_tabs

vi conf.py
extensions = ['myst_parser','sphinx_tabs.tabs']

::::{tabs}
:::{tab} python
``` print('hello')```
:::
:::{tab} shell
```echo hello```
:::
::::

效果：

print('hello')

3.3. markdown Admonitions types#

attention, caution, danger, error, hint, important, note, seealso, tip, warning

:::{note}
**提示**
加上上面这行就可以写小技巧了
:::

效果：

备注

提示 加上上面这行就可以写小技巧了

其他样式 attention, caution, danger, error, hint, important, note, seealso, tip, warning

注意

attention

3.3.1 admonition options#

class: A space-separated list of CSS classes to add to the admonition, conforming to the identifier normalization rules. name: A reference target for the admonition (see cross-referencing).

:::{tip}
:class: myclass1 myclass2
:name: a-tip-reference
Let's give readers a helpful hint!
:::

[Reference to my tip](#a-tip-reference)

效果：

小技巧

Let’s give readers a helpful hint!

Reference to my tip

3.3.2 Collapsible admonitions#

pip install sphinx_togglebutton
extensions = ['myst_parser', 'sphinx_togglebutton']

:::{note}
:class: dropdown

This admonition has been collapsed,
meaning you can add longer form content here,
without it taking up too much space on the page.
:::

效果：

备注

This admonition has been collapsed, meaning you can add longer form content here, without it taking up too much space on the page.

3.3.3 additional admonition types#

:::{versionadded} 1.2.3
Explanation of the new feature.
:::

:::{versionchanged} 1.2.3
Explanation of the change.
:::

:::{deprecated} 1.2.3
Explanation of the deprecation.
:::

Added in version 1.2.3: Explanation of the new feature.

在 1.2.3 版本发生变更: Explanation of the change.

自 1.2.3 版本弃用: Explanation of the deprecation.

3.3.4 custom admonitions with Markdown#

:::{admonition} My custom title with *Markdown*!
:class: tip

This is a custom title for a tip admonition.
:::

My custom title with Markdown!

This is a custom title for a tip admonition.

3.3.5 Other Containers (grids, tabs, cards, etc.)#

pip install sphinx_design
extensions = ['myst_parser',"sphinx_design"]

:::bg-primary
This is a container with a custom CSS class.

- It can contain multiple blocks
:::

This is a container with a custom CSS class.

  • It can contain multiple blocks

:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

Header

Card Title

Card content

Footer

::::{tab-set}
:::{tab-item} Label1
Content 1
:::
:::{tab-item} Label2
Content 2
:::
::::

Content 1

Content 2

3.4 copy code button#

pip install sphinx_copybutton
extensions = ['myst_parser','sphinx_copybutton']

5. 是否显示markdow rst 源码按钮#

html_show_sourcelink = False

7. 显示标题级别#

# 配置 MyST 解析器（确保每个文件仅显示顶级标题）
# myst_heading_anchors = 1  # 仅生成顶级标题的锚点

8. Grid#

# xs sm md lg 屏幕大小超小屏（手机） 小屏幕（平板） 中等屏幕（桌面显示器） 大屏幕（大桌面） 
````{grid} 1 1 2 2
:gutter: 3

```{grid-item-card}
User Interfaces
^^^^^^
* [JupyterLab](https://github.com/jupyterlab/jupyterlab)
* [Jupyter Notebook](https://jupyter-notebook.readthedocs.io/en/latest/)```

```{grid-item-card}
JupyterHub
^^^^^^
* [JupyterHub](https://jupyterhub.readthedocs.io/en/latest)
* [Configurable HTTP proxy](https://github.com/jupyterhub/configurable-http-proxy)```

```{grid-item-card}
Working with Notebooks
^^^^^^
* [nbclient](https://nbclient.readthedocs.io/en/latest/) - execution
* [nbconvert](https://nbconvert.readthedocs.io/en/latest/) - conversion```

```{grid-item-card}
IPython
^^^^^^
* [IPython](https://ipython.readthedocs.io/en/stable/)
* [ipykernel](https://ipython.readthedocs.io/en/stable/)```  ````

User Interfaces

JupyterHub

Working with Notebooks

IPython

9. csv-table#

```{csv-table}
:header: Site, Description
:widths: 18, 35

[Jupyter website](https://jupyter.org), Keep up to date on Jupyter
[IPython website](https://ipython.org), Learn more about IPython
[Jupyter Discourse forum](https://discourse.jupyter.org/), Start here for help and support questions```

Site

Description

Jupyter website

Keep up to date on Jupyter

IPython website

Learn more about IPython

Jupyter Discourse forum

Start here for help and support questions

10. 插入目录#

(ref-content1)=

```{toctree}
:maxdepth: 2

../demo```

11. 索引#

- {ref}`genindex`
- {ref}`search`

12. 从代码生成文档#

#从代码生成文档
sphinx-apidoc -o source/testdoc/ ../../code_path/

vi conf.py

# 从源码生成文档，build时源码和文档关联
import os
import sys
sys.path.insert(0, os.path.abspath('../../../code_path/'))  # 将项目根目录添加到模块查找路径中去

extensions = [
              #生成文档
              'sphinx.ext.autodoc',
              #显示源码
              'sphinx.ext.viewcode',
             ]
On this page
Edit on Gitea