documents/linx6090-to-makepdf.md

90最小环境安装sphinx用于md生成pdf

背景

本文为42自动编译系统，添加自动生成新版发布文档时，自动编写md文件，然后使用此环境转换md为pdf文档，用于发布。

文本为环境成功后，对制作过程进行总结记录。

说明： 此最小环境为放在自动编译机（物理机）的编译环境（虚拟机）中的/home/x86_64-workder下。环境中的某些添加脚本为特定为当前要求进行修改添加。

环境准备

获取最小环境

wget http://42.builder.rd.in.linx/chroot-env/linx6090-stretch-amd64-base.tgz

创建环境目录，并将环境挂载

mkdir /home/x86_64-workdir/linx6090-stretch-amd64-base
cp linx6090-stretch-amd64-base.tgz /home/x86_64-workdir/linx6090-stretch-amd64-base
cd /home/x86_64-workdir/linx6090-stretch-amd64-base
tar -xf linx6090-stretch-amd64-base.tgz
mount --bind /dev ./dev
mount --bind /proc ./proc
mount --bind /sys ./sys
mount --bind /dev/pts ./dev/pts
chroot .

安装包

1. 注意修改域名解析文件（/etc/resolv.conf）

 cat /etc/resolv.conf
#nameserver 192.168.122.1
nameserver 172.31.255.3

apt-get update
apt-get install fonts-wqy-microhei  fonts-wqy-zenhei  xfonts-wqy graphicsmagick-imagemagick-compat python3-pip latexmk texlive-lang-chinese texlive-xetex fonts-freefont-otf pandoc fonts-lmodern texlive-fonts-recommended fonts-wqy-microhei fonts-wqy-zenhei ttf-wqy-microhei ttf-wqy-zenhei xfonts-wqy locales

2. 安装sphinx等python模块

root@linx:~# pip3 install sphinx -i https://mirrors.aliyun.com/pypi/simple/
root@linx:~# pip3 install recommonmark -i https://mirrors.aliyun.com/pypi/simple/
root@linx:~# pip3 install sphinx_markdown_tables -i https://mirrors.aliyun.com/pypi/simple/
root@linx:~# pip3 install sphinx_rtd_theme -i https://mirrors.aliyun.com/pypi/simple/

3. 注意sphinx会安装到/usr/local下，需要配置环境变量PATH

cat /root/.bashrc
PATH="/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:$PATH"

4. 配置语言环境，注意选zh_CN.UTF-8

dpkg-reconfigre locales

5. 创建项目目录并在项目目录中运行 sphinx-quickstart命令进行配置。

   root@linx:/# mkdir 42-builder
   root@linx:/# cd 42-builder
   root@linx:/42-builder# sphinx-quickstart
   欢迎使用 Sphinx 2.4.4 快速配置工具。
   
   请输入接下来各项设置的值（如果方括号中指定了默认值，直接
   按回车即可使用默认值）。
   
   已选择根路径：.
   
   布置用于保存 Sphinx 输出的构建目录，有两种选择。
   一是在根路径下创建“_build”目录，二是在根路径下创建“source”
   和“build”两个独立的目录。
   > 独立的源文件和构建目录（y/n） [n]: y
   
   项目名称会出现在文档的许多地方。
   > 项目名称: sphinx生成pdf搭建过程
   > 作者名称: 技术工程部
   > 项目发行版本 []: v1
   
   If the documents are to be written in a language other than English,
   you can select a language here by its language code. Sphinx will then
   translate text that it generates into that language.
   
   For a list of supported codes, see
   https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
   > 项目语种 [en]:
   
   创建文件 ./source/conf.py。
   创建文件 ./source/index.rst。
   创建文件 ./Makefile。
   创建文件 ./make.bat。
   
   完成：已创建初始目录结构。
   
   你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。 用 Makefile 构建文档，像这样：
    make latexpdf
   此处的“latexpdf”是支持的构建器名，比如 html、latex 或 linkcheck。
   

6. 添加便于release发布脚本调用的脚本

   1. 添加stable.sh到根下

cat stable.sh
#! /bin/bash

source /root/.bashrc
cd 42-builder
make clean
make latexpdf
cd -

2) 添加获取bugzilla的title的py脚本

需要安装python的requests模块：python-requests

cat summary.py 
#!/usr/bin/python

import os
import requests
from optparse import OptionParser  


def main():  
	usage = "usage: %prog [options] arg"  
	parser = OptionParser(usage)  
	parser.add_option("-n", "--num", dest="num",  
			help="the bug's num")  

	(options, args) = parser.parse_args()  
	print options.num
	r=requests.get('http://bugzilla.rd.in.linx/bugzilla/rest.cgi/bug/%s?include_fields=summary' % (options.num))
	if r:
		s=unicode(r.text).encode('utf8')
		output=open('bug_title','w')
		output.writelines(s)
		output.close
	else :
		output=open('bug_title','w')
		print 'Bug_not_found!'
		output.writelines('Bug_not_found!')
		output.close


if __name__ == "__main__":  
	main()  

附：sphinx工具使用方法

root@localhost:/42-builder# find .
.
./make.bat
./build
./Makefile
./source
./source/index.rst.bak
./source/_static
./source/_static/logo.jpg
./source/_templates
./source/index.rst
./source/conf.py
./source/2020-03-17-005002.md

使用方法：

1. 将需要转换的md文件拷贝到source下，然后配置index.rst文件（将要转换的文件名添加到index.rst中，注意开头的空格数，必须对齐，初次使用时，建议先拷贝使用）

root@localhost:/42-builder/source# cat index.rst
.. 6.0.42-builder documentation master file, created by

Welcome to 6.0.42-builder's documentation!
==========================================

.. toctree::
    :maxdepth: 2
    :numbered:
    :glob:
    :caption: 目录:

    2020-03-17-005002.md

2. 配置文件conf.py

配置规则，配置页脚，文档名称，版本号,字体等(初次使用时，建议直接拷贝使用)

cat conf.py 
#Configuration file for the Sphinx documentation builder.
#
#This file only contains a selection of the most common options. For a full
#list see the documentation:
#https://www.sphinx-doc.org/en/master/usage/configuration.html

#-- Path setup --------------------------------------------------------------

#If extensions (or modules to document with autodoc) are in another directory,
#add these directories to sys.path here. If the directory is relative to the
#documentation root, use os.path.abspath to make it absolute, like shown here.
#
#import os
#import sys
#sys.path.insert(0, os.path.abspath('.'))
import sphinx_rtd_theme
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

#-- Project information -----------------------------------------------------

project = '凝思rocky6.0.42'
copyright = '2018-, 北京凝思科技有限公司'
author = '凝思科技有限公司'

#The full version, including alpha/beta/rc tags
release = '1.0'


#-- General configuration ---------------------------------------------------

#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_markdown_tables',
#            'sphix_maketitle': [
#                            '_static/sphixmaketitle',
#                            ],
            ]

#Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

#The language for content autogenerated by Sphinx. Refer to documentation
#for a list of supported languages.
#
#This is also used if you do content translation via gettext catalogs.
#Usually you set "language" from the command line for these cases.
language = 'zh_CN'
html_search_language='zh'
#html_search_options={'dict':'user_dict'}

#List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
#This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


#-- Options for HTML output -------------------------------------------------

#The theme to use for HTML and HTML Help pages.  See the documentation for
#a list of builtin themes.
html_theme = 'sphinx_rtd_theme'

#Add any paths that contain custom static files (such as style sheets) here,
#relative to this directory. They are copied after the builtin static files,
#so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

html_context = {
            'css_files': [
                        '_static/theme_overrides.css',  # override wide tables in RTD theme
                                ],
                 }
#编辑配置文件source/conf.py在最后一行复制下方配置
from recommonmark.parser import CommonMarkParser
source_parsers = {
            '.md': 'recommonmark.parser.CommonMarkParser',
            }

source_suffix = ['.rst', '.md']
latex_engine = 'xelatex'
latex_logo = '_static/logo.jpg'
#latex定制选项,包括字体、首行缩进等
latex_elements = {
            'fontpkg': r'''
            \setmainfont{WenQuanYi Micro Hei}
            \setsansfont{WenQuanYi Micro Hei}
            \setmonofont{WenQuanYi Micro Hei Mono}
            ''',
            'preamble': r'''
            \usepackage[titles]{tocloft}
            \usepackage{indentfirst}
            \setlength{\parindent}{2em}
            \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
            \setlength{\cftchapnumwidth}{0.75cm}
            \setlength{\cftsecindent}{\cftchapnumwidth}
            \setlength{\cftsecnumwidth}{1.25cm}
            \hypersetup{unicode=true}
            \usepackage{CJKutf8}
            ''',
            'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
            'printindex': r'\footnotesize\raggedright\printindex',
            }
latex_show_urls = 'footnote'

3. logo文件

logo图片为文档头上的linx图。

4. cd到42-builder目录下执行make clean;然后执行make latexpdf

生成的pdf文档，在build/latex下