1、安装

python环境这里就不介绍了

#安装主题 sphinx_rtd_theme 的markdown

pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables

2、生成html

新建app_tower目录

2.1进入该目录，执行sphinx-quickstart

执行完毕后，就可以看见创建的工程文件

_build：文件夹，当你执行make html的时候，生成的html静态文件都存放在这里
_static：文件夹：图片,js等存放地址
_templates：文件夹:模板文件存放
make.bat：bat脚本
Makefile:编译文件
index.rst:索引文件,文章目录大纲
conf.py:配置文件

2.2、编写文章

在app_tower目录下新建hello.rst,内容如下:

hello,world
=============

如果会markdown语法,无需学习rst语法,可参考文末语法转换网站.

index.rst修改如下:

.. toctree:::maxdepth: 2hello

然后在 app_tower 目录下执行 make html,

进入 _build/html 目录后用浏览器打开 index.html

2.3更改主题和添加md支持

vim conf.py #更改如下配置:

html_theme = "sphinx_rtd_theme"
extensions = ['recommonmark']

然后再次运行 make html 即可.
关于markdown的用法形式与rst一样,直接更换后缀并在文件内已markdown语法写内容即可.

部署的话，直接复制html文件夹里面的内容到服务器即可。

浏览器效果图如下：

3、生成pdf

3.1导入rst2pdf

pip  install rst2pdf

需要告诉sphinx我们安装了rst2pdf，并且将其作为插件使用。只需在项目根目录下的conf.py中配置

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc','rst2pdf.pdfbuilder'
]

即可。然后，在conf.py中拷入PDF相关的配置


# -- Options for PDF output --------------------------------------------------# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document.
# For example,
# ('index', u'MyProject', u'My Project', u'Author Name',
# dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.pdf_documents = [('index', u'进出站小程序操作手册', u'进出站小程序操作手册', u'田立、曾书、韩立'),
]# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['aA','zh_CN']# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
#pdf_compressed = False# A colon-separated list of folders to search for fonts. Example:
pdf_font_path = ['C:\\Windows\\Fonts']# Language to be used for hyphenation support
pdf_language = "zh_CN"# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
pdf_fit_mode = "shrink"# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
#pdf_break_level = 0# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
#pdf_breakside = 'any'# Insert footnotes where they are defined instead of
# at the end.
#pdf_inline_footnotes = True# verbosity level. 0 1 or 2
#pdf_verbosity = 0# If false, no index is generated.
pdf_use_index = False# If false, no modindex is generated.
#pdf_use_modindex = True# If false, no coverpage is generated.
#pdf_use_coverpage = True# Documents to append as an appendix to all manuals.
#pdf_appendices = []# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
#pdf_splittables = False# Set the default DPI for images
#pdf_default_dpi = 72# Enable rst2pdf extension modules (default is only vectorpdf)
# you need vectorpdf if you want to use sphinx's graphviz support
#pdf_extensions = ['vectorpdf']# Page template name for "regular" pages
#pdf_page_template = 'cutePage'# Show Table Of Contents at the beginning?
pdf_use_toc = False# How many levels deep should the table of contents be?
pdf_toc_depth = 1# Add section number to section references
pdf_use_numbered_links = False# Background images fitting mode
pdf_fit_background_mode = 'scale'

具体配置项的值请自行调整，不需要严格按照我的来。

样式表

3.2在项目根目录下创建一个zh_CN.json

写入：

{"embeddedFonts": ["simsun.ttc"],"fontsAlias": {"stdFont": "simsun","stdBold": "simsun","stdItalic": "simsun","stdBoldItalic": "simsun","stdMono": "simsun","stdMonoBold": "simsun","stdMonoItalic": "simsun","stdMonoBoldItalic": "simsun","stdSans": "simsun","stdSansBold": "simsun","stdSansItalic": "simsun","stdSansBoldItalic": "simsun"},"styles": [["base",{"wordWrap": "CJK"}],["literal",{"wordWrap": "None"}]]
}

然后配置编译脚本

Windows用户，在make.bat中加入：

if "%1" == "pdf" (%SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdfif errorlevel 1 exit /b 1echo.echo.Build finished. The pdf files are in %BUILDDIR%/pdf.goto end
)

3.3输出PDF

然后一句：

make pdf

参考：

https://www.jb51.net/article/86046.htm

使用sphinx+markdown来编写文档,生成html和pdf相关推荐

如何使用Markdown语言编写文档
目录 Markdown 语言简介 Markdown基础语法一.标题二.段落格式 1. 字体 2. 分隔线 3. 删除线 4. 下划线 5. 脚注三.列表 1. 无序列表 2. 有序列表 3. 列 ...
sphinx：基于 Python 的文档生成工具
sphinx:基于 Python 的文档生成工具 Motivation 对于软件开发来说,文档是软件可维护性的重要保障.sphinx 是一款文档生成工具,以 restructuredText 为标记语 ...
关于深度学习框架Hamaa与Python API文档生成工具Sophon
五月两场 | NVIDIA DLI 深度学习入门课程 5月19日/5月26日一天密集式学习快速带你入门阅读全文> 正文共1988个字,预计阅读时间12分钟. 前言最近三个月我主要花时间在造 ...
python文档生成_python文档生成工具：pydoc、sphinx；django如何使用sphinx？
文档生成工具: 自带的pydoc,比较差建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...
易文档（yidocs），更简单的markdown静态文档生成模板
基本简介 yidocs(易文档),是在 vuepress 主题 vuepress-theme-hope 基础上,进一步简化使用的文档模板. 大部分配置和参数都有默认值,使用 yidocs(易文档)的用 ...
扔掉Swagger，试试这款功能强大，零注解侵入的API接口文档生成工具！
欢迎关注方志朋的博客,回复"666"获面试宝典介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart-d ...
一款零注解侵入的 API 文档生成工具，你用过吗？
以下文章来源方志朋的博客,回复"666"获面试宝典介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart ...
支持Dubbo接口文档生成的工具！
点击上方蓝色"程序猿DD",选择"设为星标" 回复"资源"获取独家整理的学习资料! 作者 | 肥朝来源 | https://mp.weix ...
wsdl文档中的soap:address的生成规则_BAT大牛都在使用的数据库文档生成插件,不来看一下？...
一.概述在企业级开发中.我们经常会有编写数据库表结构文档的时间付出,从业以来,待过几家企业,关于数据库表结构文档状态:要么没有.要么有.但都是手写.后期运维开发,需要手动进行维护到文档中,很是繁琐. ...
一款零注解API接口文档生成工具
smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,基于接口源码来分析生成接口文档,不采用任何注解侵入到业务代码中.只需要按照java-do ...

使用sphinx+markdown来编写文档,生成html和pdf