Sphinx培训

你现在看到的页面就是用Sphinx搭建的wiki, Sphinx是一个工具，可以轻松创建智能和美观文档，下面的内容就是详细的介绍它的使用。

Wiki语法

gui

Cancel

Start ‣ Programs

Apr 27, 2020

LIFO. （鼠标移上去，出现提示文字）

:guilabel:`&Cancel`
:menuselection:`Start --> Programs`
|today|
:abbr:`LIFO (last-in, first-out)`.

today_fmt = '%Y-%m-%d' #'%B %d, %Y'

code

所有支持的语言：http://pygments.org/languages/

.. code-block:: ActionScript
   :emphasize-lines: 3,4
   :linenos:

note

See also

This is a simple seealso note.

Note

This is a simple note note.

<!– .. todo:: This is a simple todo note. need add this in conf.py: todo_include_todos=True –>

Warning

This is a simple warning note. .. include:: ./todo-tutorial.md

文字随便写

这里写文字。 put into conf.py:

import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']

这里也可以写文字。

.. seealso:: This is a simple **seealso** note.
.. note:: This is a simple **note** note.
.. todo:: This is a simple **todo** note. need add this in conf.py: todo_include_todos=True
.. warning:: This is a simple **warning** note. .. include:: ./todo-tutorial.md

.. admonition:: 文字随便写

   这里写文字。
   put into conf.py::

      import sys, os
      sys.path.append(os.path.abspath('exts'))
      extensions = ['foo']

   这里也可以写文字。

color

Red word
.. raw:: html

   <font color="red">Red word</font>

includefile

.. literalinclude:: ../_static/forms-ex600/app/app.component.ts
   :linenos:
   :language: typescript
   :lines: 1, 2-39

.. code-block:: typescript
   :linenos:

   this.form.controls['make'].valueChanges.subscribe(
      (value) => { console.log(value); }
   );
   this.form.controls['make'].statusChanges.subscribe(
      (value) => { console.log(value); }
   );

.. include:: ./Application.md

image

.. image:: images/Figure19-7.png
   :width: 400px
   :align: center
   :height: 200px
   :alt: alternate text

table

The following table lists some useful lexers (in no particular order).

Frozen Delights!
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49 If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple 1.99 On a stick!
Frozen Delights!
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49
If we took the bones out, it wouldn’t be
crunchy, now would it?
Gannet Ripple 1.99 On a stick! 
.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
      crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

隐藏source

html_show_sourcelink = False

Custom CSS

custom stylesheet is _static/css/custom.css:

## conf.py

# These folders are copied to the documentation's HTML output
html_static_path = ['_static']

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
   'css/custom.css',
]

Html

html_favicon = 'favicon.ico'
html_logo = 'sphinx.svg'
html_title = ''

chapters

# 及上划线表示部分
* 及上划线表示章节
=, 小章节
-, 子章节
^, 子章节的子章节
", 段落

highlight

The literal blocks are now highlighted as HTML, until a new directive is found.

<html><head></head>
<body>This is a text.</body>
</html>

The following directive changes the hightlight language to SQL.

SELECT * FROM mytable

From here on no highlighting will be done.

SELECT * FROM mytable

脚注

首先在正文中有个序号 [1] ，然后在页面的尾部 .. rubric:: 脚注。

Error

当执行make html命令时出现类似下面的错误信息时，是由于根目录的权限不够导致的，需要执行chmod 777 放开目录权限:

reading sources... [100%] pages/netflix
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... WARNING: search index couldn't be loaded, but not all documents will be built: the index will be incomplete.
done
writing output... [100%] pages/netflix
generating indices... genindex
writing additional pages... search

部署到github

  1. 在github上创建仓库，根目录下新建文件夹 docs 。
  2. 拷贝wiki到 docs 目录下。
  3. 提交代码。
  4. 使用github账号登陆 Read the Docs 网站。
  5. 选择导入的github上创建的仓库。
  6. 按照步骤一步步操作，最终build结果如下：
<!– .. image:: images/wiki_1.png
width:600px –>

参考

任何文字（如：脚注）

[1]演示脚注 .. include directive, 点击左边的【1】迅速定位到上面的 脚注 处。