02Sphinx案例之rst语法笔记

简介¶

接下来我将使用sphinx整理一个笔记，进一步熟悉sphinx，笔记的内容就选择整理一下rst的语法吧，毕竟markdown语法比较简单，并不太需要什么笔记。rst是sphinx默认支持的语法，语法比较复杂，需要经常翻阅多次才能熟练使用。

笔记最终效果如下：

这个主题是：piccolo_theme，这个也是我比较喜欢的一个主题，还有其它类似pyData也很好看。左侧是不同的文档(或者一级标题)，右侧是单个文档的目录，方便定位查看，搜索功能也不错，虽然不能预览全文，但搜索功能是全文搜索的，不止是标题。

正文¶

首先先安装一下主题

pip install piccolo_theme

然后修改source/conf.py文件，把html_theme变量赋值为piccolo_theme

html_theme = 'piccolo_theme'

这时候编译，生成html打开看一下：

.\make.bat html

就表示主题可以正常使用了。

‍

接下来，加入内容：

在source文件夹下新建一个docs，用来存放所有的笔记文件

这里我提前写好了一些笔记内容：

这个是rst语法写的，后面再展示markdown写的

写好的内容此时编译，依然html是不会自动加入这些内容的，需要修改source/index.rst文件里面写入如下内容：

.. 我的笔记 documentation master file, created by
   sphinx-quickstart on Wed Apr 10 23:07:54 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to 我的笔记's documentation!
====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :glob:

   docs/*

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

这是rst语法，写完之后，再次编译预览一下：

基本完成了大部分内容了。

等学会rst语法之后，就可以自己修改source/index.rst内容，来改变这个笔记的主页了。

比如我现在打开是这样的，我修改一下source/index.rst内容如下：

.. 两个点开头是表示注释，
   和python里面的#是一样的，这就说明这些注释是不会被渲染到网页的
   多行注释，缩进就行

我的笔记: rst语法
==================

这是我的第一个sphinx笔记

这个语法文档源码: https://github.com/yanggenjie/rstSyntax

本文语法来自 `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_。

内容参考了:

* `reStructuredText语法文档 <https://3vshej.cn/rstSyntax/>`_

下面是创建子目录目录，同时也是整个文档的右侧目录导航，在index文件中，toctree是必不可少的哦

-------------

.. toctree::
   :maxdepth: 2
   :glob:

   docs/*



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

再预览一下：

本文档源码: https://github.com/yanggenjie/rstSyntax

‍

02Sphinx案例之rst语法笔记

简介¶

正文¶

评论