使用sphinx生成美观的文档

Posted llguanli

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了使用sphinx生成美观的文档相关的知识,希望对你有一定的参考价值。

先上效果图

技术分享


详情

首先,须要知道什么是restructuredtext。能够理解为类似于markdown的一个东西。

然后

  1. 安装。pip install sphinx
  2. 进入存放文档的文件夹,在命令行,sphinx-quickstart,依据须要一路回车。会生成一堆东西,包含conf.py和make等
  3. 依据须要改动conf.py
  4. 编写rst文件。比方默认的index.rst或链接的rst文件。
  5. 在命令行,make html

上图的效果,是使用了一个主题叫sphinx_bootstrap_theme。

(PS.有非常多主题能够选择)

conf.py中关于这个主题的配置是加了以下几行代码

import sphinx_bootstrap_theme
html_theme = ‘bootstrap‘
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {
    ‘navbar_title‘: "Sandglass",
    ‘globaltoc_depth‘: 2,
    ‘globaltoc_includehidden‘: "true",
    ‘navbar_class‘: "navbar navbar-inverse",
    ‘navbar_fixed_top‘: "true",
    ‘bootswatch_theme‘: "united",
    ‘bootstrap_version‘: "3",
}


生成的文档的目录布局

技术分享


图中的index.rst文件

Welcome to sandglass‘s documentation!
=====================================

安装
------------

  pip install sandglass


概览
--------

**sandglass(沙漏)** 是一个增强的、友好的时间处理库。目的是为了解放程序猿的生产力。

在python中有太多处理时间的库,datetime/date/time/calendar等等。须要记的细节太多,选择困难。 而sandglass就是解决这个的青霉素。从各种麻烦的转换中解脱出来。

仅仅需记住 **Sandglass对象** 和 **ben()** 、 **tslice()** 、 **cronwalk()** 这几个基本的api就可以。

特性 ---------- + api简洁。开箱即用 + 增强接管datetime + (此次略去xx字) 高速上手 --------- 在sandglass中,核心对象是 **Sandglass对象** 。通过这个对象。能够方便的获取各个时间属性和操作:: #获取属性 >>>sg = ben(‘2013,1,1 13:14:15‘) >>>sg.year,sg.month,sg.day,sg.hour,sg.minute,sg.second,sg.microsecond (2013, 1, 1, 13, 14, 15, 0) (此次略去xx字) API文档 ----------------- .. toctree:: :maxdepth: 2 api Todo --------- * Add timezone support Changelog --------- **0.0.1** * Initial release Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`



很多其它详情请看sphinx的官方文档

以及sphinx-bootstrap-theme主题的官方文档












以上是关于使用sphinx生成美观的文档的主要内容,如果未能解决你的问题,请参考以下文章

sphinx快速生成Python API文档

python代码docstring生成文档之sphinx

使用sphinx快速生成Python API 文档

文档工具的王者Sphinx

Sphinx - 在代码块片段中使用省略号 (...)

如何使用 Sphinx 为 Python 属性设置器生成文档?