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 0000000..5211724 Binary files /dev/null and b/logo.jpg differ