sphinx语法小记

发表于   |   分类于   |     |   次阅读

在刷LeetCode的时候，发现用博客来记录太麻烦，所以选择了Python的免费文档readthedocs来记录自己的刷题记录，博客还是用来记录自己的所学和感悟。

第一次接触rst语法的时候还很不习惯，毕竟以前都是用Markdown来写文章，现在突然换一种方式还是有点措手不及，写过一阵子后发现也还行，现在在这里给大家分享一下自己的认识，也方便自己以后查阅。

在写文档的时候，跟Markdown的来走，首先是标题的分级，Python的语法很奇怪，自己感觉最主要还是格式的要求，对于空格space是非常严格的

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Level 1  //类似于markdown的#
=======

===================================================
This is level 1 too, but looks better in plain text
===================================================

Level 2
-------

Level 3
^^^^^^^

Level 4
"""""""

接下来是非常有意思的一个地方，sphinx给了很多默认的注解样式，如果使用的得当，会让页面显得非常好看，让人很想去欣赏

1
2
3
4
5
.. attention::
      不在于刷了多少题目，一定要理解每一次刷的题目


caution、danger、error、hint、important、note、tip、warning、admonition

需要说一下最后一个admonition的用法，这个就是属于自定义标签的感觉, 用法如下

1
2
3
4
5
6
7
.. admonition:: 保爷语录
    
    10不在于刷了多少题目，一定要理解每一次刷的题目

.. admonition:: And, by the way...

   You can make up your own admonition too.

标记 含义
*emphasis* def
**strong emphasis** def2
`interpreted text` dsfsdf
reference_ 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.. metadata-placeholder

   :DC.Title: 
      Generic links to be available in all documents
   :DC.Creator: 
      Nery, Fernanda
   :DC.Language:
      en
   :DC.Format:
      text/x-rst 
   :DC.Description
      This is a partial file at::
         /docs/source/On_Documentation/Z_GenericLinks.txt
         
      Link it to the master file at:: 
      
         /docs/source/Z_SharedFiles/Z_GenericLinks.txt
         
      with the following directive::
      
         .. include:: ../On_Documentation/Z_GenericLinks.txt
         
.. links-placeholder

.. _add Distribute and Pip to the Python installation: https://python-guide.readthedocs.org/en/latest/starting/install/win.html#distribute-pip

.. _Sphinx's reStructuredText Primer: http://sphinx-doc.org/_sources/rest.txt
.. _reStructuredText User Documentation: http://docutils.sourceforge.net/rst.html

用sphinx写好的文档可以转成pdf格式，以前不是说自己要写一本书么，现在就可以实现了，而且都是可以按照自己的风格来排版，到时候自己出钱就可以出书了，是不是感觉特别棒。

  1. Install rst2pdf

    • use your package manager (or)
    • pip install rst2pdf (or)
    • easy_install rst2pdf

  2. Add rst2pdf to the list of extensions in conf.py
    extensions = [‘rst2pdf.pdfbuilder’]

This list will be empty if you accepted the defaults when the project was setup. If not, just append ‘rst2pdf.pdfbuilder’ to the list.

  1. Add a pdf_documents variable to conf.py

    1
    2
    3
    4
    5
    pdf_documents = [('index', u'rst2pdf', u'Sample rst2pdf doc', u'Your Name'),]
    # index - master document
    # rst2pdf - name of the generated pdf
    # Sample rst2pdf doc - title of the pdf
    # Your Name - author name in the pdf

  2. Generate pdf
    sphinx-build -b pdf source build/pdf
    The generated pdf will be in the build/pdf directory.

http://docutils.sourceforge.net/docs/ref/rst/directives.html

http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions

https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst