资料
官网：http://www.sphinx-doc.org
最全教程见：http://www.pythondoc.com/sphinx/contents.html
参考资料：
sphinx入门指南【1】快速入门：https://www.jianshu.com/p/de731c4b94a0
sphinx入门指南【2】 toctree指令详解：https://www.jianshu.com/p/ded9e52eaebd
环境：Python 3.6/Win10
摘要
想通过Markdown编写技术文档，然后发布到WEB上面，经过研究发现Sphinx比较适合。
Sphinx是一个基于Python的文档生成项目，最早只是用来生成 Python 官方文档，随着工具的完善， 越来越多的知名的项目也用他来生成文档。
支持将Markdown生成html/epub/singlehtml/pdf。
一、安装Sphinx
pip install sphinx sphinx-autobuild sphinx_rtd_theme
二、初始化项目
2.1 创建项目
# 创建文档根目录 mkdir -p /root/work/scrapy-cookbook cd scrapy-cookbook/ # 可以回车按默认配置来写 sphinx-quickstart
2.2 编译项目
.make.bat html
3.2 浏览文档
安全安装nodesjs插件http-server后，执行：
http-server -c-1
（-c-1为禁止缓存）
三、切换成sphinx_bootstrap_theme主题
3.1 安装依赖
pip install sphinx_bootstrap_theme
3.2 将项目主题切换至sphinx_bootstrap_theme
编辑conf.py，修改并添加以下部分
# At the top. import sphinx_bootstrap_theme # ... # Activate the theme. html_theme = 'bootstrap' html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
3.3 自定以主题
将以下内容添加至conf.py
# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
# Path should be relative to the ``_static`` files directory.
# html_logo = "my_logo.png"
# Theme options are theme-specific and customize the look and feel of a
# theme further.
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
# 'navbar_title': "帮助中心",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "目录",
# A list of tuples containing pages or urls to link to.
# Valid tuples should be in the following forms:
# (name, page) # a link to a page
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
# (name, "http://example.com", True) # arbitrary absolute url
# Note the "1" or "True" value above as the third argument to indicate
# an arbitrary url.
'navbar_links': [
("控制台", "console/index"),
("主页", "http://www.com.cn", True),
],
# Render the next and previous page links in navbar. (Default: true)
'navbar_sidebarrel': False,
# Render the current pages TOC in the navbar. (Default: true)
'navbar_pagenav': True,
# Tab name for the current pages TOC. (Default: "Page")
'navbar_pagenav_name': "当页导航",
# Global TOC depth for "site" navbar tab. (Default: 1)
# Switching to -1 shows all levels.
'globaltoc_depth': 2,
# Include hidden TOCs in Site navbar?
#
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
# non-hidden ``toctree`` directives in the same page, or else the build
# will break.
#
# Values: "true" (default) or "false"
'globaltoc_includehidden': "true",
# HTML navbar class (Default: "navbar") to attach to <div> element.
# For black navbar, do "navbar navbar-inverse"
# 'navbar_class': "navbar navbar-inverse",
# Fix navigation bar to top of page?
# Values: "true" (default) or "false"
'navbar_fixed_top': "true",
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
'source_link_position': "exclude", # 去掉打开源码的链接
# Bootswatch (http://bootswatch.com/) theme.
#
# Options are nothing (default) or the name of a valid theme
# such as "cosmo" or "sandstone".
#
# The set of valid themes depend on the version of Bootstrap
# that's used (the next config option).
#
# Currently, the supported themes are:
# - Bootstrap 2: https://bootswatch.com/2
# - Bootstrap 3: https://bootswatch.com/3
'bootswatch_theme': "flatly", #united 这里可以选很多种风格，具体见：https://bootswatch.com/cosmo/
# Choose Bootstrap version.
# Values: "3" (default) or "2" (in quotes)
'bootstrap_version': "3",
}
四、支持Markdown语法
4.1 安装依赖
pip install recommonmark
4.2 修改配置conf.py
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
附、参考链接
sphinx_bootstrap_theme官方：https://github.com/ryan-roemer/sphinx-bootstrap-theme
sphinx_bootstrap_theme风格网站：https://bootswatch.com/
参考教程：https://www.xncoding.com/2017/01/22/fullstack/readthedoc.html