From ea5dbd17423cfc660ea23d7cd1872489c98b9017 Mon Sep 17 00:00:00 2001 From: "Xu, Shunxuan" Date: Wed, 25 Mar 2020 18:05:10 +0800 Subject: [PATCH] =?UTF-8?q?90=E4=BD=BF=E7=94=A8sphinx=E8=BD=AC=E6=8D=A2md?= =?UTF-8?q?=20to=20pdf?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修改： README.md 新文件： linx6090-to-makepdf.md 新文件： logo.jpg Signed-off-by: Xu, Shunxuan --- README.md | 2 + linx6090-to-makepdf.md | 322 +++++++++++++++++++++++++++++++++++++++++ logo.jpg | Bin 0 -> 3387 bytes 3 files changed, 324 insertions(+) create mode 100644 linx6090-to-makepdf.md create mode 100644 logo.jpg diff --git a/README.md b/README.md index 3c985a3..65a1478 100755 --- a/README.md +++ b/README.md @@ -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) diff --git a/linx6090-to-makepdf.md b/linx6090-to-makepdf.md new file mode 100644 index 0000000..dfbbba2 --- /dev/null +++ b/linx6090-to-makepdf.md @@ -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图。 + +![logo](logo.jpg) + +4. cd到42-builder目录下执行make clean;然后执行make latexpdf + +生成的pdf文档，在build/latex下 + + diff --git a/logo.jpg b/logo.jpg new file mode 100644 index 0000000000000000000000000000000000000000..52117242f2b130e91c2dc3558d03a5196268167f GIT binary patch literal 3387 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 literal 0 HcmV?d00001