基于Sphinx使用Markdown生成HTML/PDF/epub文档

资料

官网：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