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

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: 2

   hello

然后在 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%/pdf
  if errorlevel 1 exit /b 1
  echo.
  echo.Build finished. The pdf files are in %BUILDDIR%/pdf.
  goto end
)

3.3输出PDF

然后一句：

make pdf

参考：

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