Sphinx 扩展

地震“学”的教程文档使用了一些 Sphinx 扩展,以便简洁而有效地组织文档内容。本章主要介绍常用扩展的常用用法。

sphinx-panels

sphinx-panels 扩展的指令在组织文档内容方面具有十分强大的功能。这里主要介绍几个常用指令的常用用法,更多指令及其用法请参考官方文档。一些指令使用的一些参数的具体含义需要了解 Bootstrap

tabbed 指令

使用 tabbed 指令可以使文档内容以选项卡的形式显示。例如,不同操作系统下安装 git:

.. tabbed:: Fedora

   ::

       $ sudo dnf install git

.. tabbed:: Ubuntu/Debian

   ::

       $ sudo apt install git

.. tabbed:: macOS

    ::

        $ brew install git

.. tabbed:: Windows

   打开 https://git-scm.com/downloads\ ,下载并安装 Git for Windows。

以上内容的显示效果:

$ sudo dnf install git
$ sudo apt install git
$ brew install git

打开 https://git-scm.com/downloads,下载并安装 Git for Windows。

panels 指令

使用 panels 指令可以使文档内容以网格布局的形式显示。例如,使用卡片布局(card layout):

.. panels::
    :container: container-lg pb-3
    :column: col-lg-3 col-md-3 col-sm-4 col-xs-6 p-2

    地震学主站
    ^^^^^^^^^^

    地震“学”网站源起于 SeisMan 博客。

    ---

    地震“学”科研入门教程
    ^^^^^^^^^^^^^^^^^^^

    - 计算机基础
    - 编程基础
    - 地震学基础
    - 地震学实践
    - 实践经验
 
    ---

    地震“学”软件
    ^^^^^^^^^^^^

    - 理论走时
    - 合成地震图
    - 震源机制反演
    - ...

    ---

    地震“学”参考书
    ^^^^^^^^^^^^^^^

    这本电子参考书将包含我们在日常科研中遇到的一些知识点

以上布局的显示效果:

地震学主站

地震“学”网站源起于 SeisMan 博客。

地震“学”科研入门教程

  • 计算机基础

  • 编程基础

  • 地震学基础

  • 地震学实践

  • 实践经验

地震“学”软件

  • 理论走时

  • 合成地震图

  • 震源机制反演

地震“学”参考书

这本电子参考书将包含我们在日常科研中遇到的一些知识点

简要介绍该指令中使用的一些参数。container 参数:

  • container-lg:控制内容的总宽度(详细请参考 Bootstrap: containers

  • pb-3:行之间的空白距离(pb 即 bottom padding)是某常数的 3 倍(详细请参考 Bootstrap: spacing

column 参数中 lg、md、sm、xs 分别表示不同大小的设备(即大型、中型、小型、超小型),而 Bootstrap 将每行分成 12 个部分,因此:

  • col-lg-3:对于大型设备,每一列占 3 个部分,所以每行有 4 列

  • col-md-3:对于中型设备,每一列占 3 个部分,所以每行有 4 列

  • col-sm-4:对于小型设备,每一列占 4 个部分,所以每行有 3 列

  • col-xs-6:对于超小设备,每一列占 6 个部分,所以每行有 2 列

  • p-2: 列之间的空白距离是某常数的 3 倍