90使用sphinx转换md to pdf
修改： README.md 新文件： linx6090-to-makepdf.md 新文件： logo.jpg Signed-off-by: Xu, Shunxuan <sxxu@linx-info.com>
This commit is contained in:
Xu, Shunxuan
@@ -50,3 +50,5 @@
|
||||
## [编译调试版glibc以及gdb调试的简单用法](glibc-debug-gdb.md)
|
||||
|
||||
## [4.2 700版支持efi](4.2-700-efi.md)
|
||||
|
||||
## [使用90系统的sphinx工具发布release_stable](linx6090-to-makepdf.md)
|
||||
|
||||
322
linx6090-to-makepdf.md
Normal file
322
linx6090-to-makepdf.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# 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命令进行配置。
|
||||
|
||||
```bash
|
||||
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下
|
||||
|
||||
|
||||
Reference in New Issue
Block a user