320 lines
13 KiB
Python
320 lines
13 KiB
Python
#!/usr/bin/python
|
||
# -*- coding: UTF-8
|
||
|
||
from __future__ import print_function
|
||
|
||
# sphinx事件回调函数
|
||
#如果copy到conf.py文件中，只copy下面的代码即可。
|
||
|
||
import os
|
||
import os.path as osp
|
||
import sys
|
||
import importlib
|
||
import traceback
|
||
import datetime as dt
|
||
import locale
|
||
|
||
#如果文档编译失败，请检查下面默认的路径是否正确，请根据实际路径进行修改
|
||
|
||
if osp.exists(osp.join(osp.dirname(__file__), './parsejson.py')):
|
||
sys.path.append(osp.join(osp.dirname(__file__), '.'))
|
||
else:
|
||
sys.path.append(osp.join(osp.dirname(__file__), '../'))
|
||
|
||
cusdirect = None
|
||
extpathisexist = False # ./_ext/customdirective.py是否存在的标志，用于设置指令扩展
|
||
|
||
extpath = osp.join(osp.dirname(__file__), './_ext')
|
||
if osp.exists(extpath):
|
||
# 自定义指令所在路径，加到搜索目录，否则无法使用自定义指令
|
||
sys.path.append(extpath)
|
||
if osp.exists(osp.join(osp.dirname(__file__),r'./_ext/customdirective.py')):
|
||
extpathisexist = True
|
||
cusdirect = importlib.import_module('customdirective')
|
||
else:
|
||
extpath = osp.join(osp.dirname(__file__), '../_ext')
|
||
sys.path.append(extpath)
|
||
if osp.exists(osp.join(osp.dirname(__file__),r'../_ext/customdirective.py')):
|
||
extpathisexist = True
|
||
cusdirect = importlib.import_module('customdirective')
|
||
|
||
import sphinx
|
||
import sphinx.errors as sperror
|
||
import parsejson
|
||
|
||
try:
|
||
import breathe # 仅为了判断版本号，根据breathe版本号添加不同配置
|
||
breathe_version = breathe.__version__[:3]
|
||
except Exception as e:
|
||
breathe_version = ""
|
||
|
||
warnfile = '' # 告警文件，不包含路径
|
||
warnfilepath = '' # 保存告警日志文件，包含完整的路径名
|
||
|
||
months=['January','February','March','April','May','June','July',
|
||
'August','September','October','Novmber','December']
|
||
|
||
gmaketitle = r'''
|
||
\pagenumbering{Roman}
|
||
\begin{titlepage}
|
||
\centering
|
||
\vspace*{40mm}
|
||
\textbf{\Huge {%(titlename)s}}
|
||
|
||
\vspace{10mm}
|
||
\textbf{\Large{%(release)s}}
|
||
|
||
\vfill
|
||
\textbf{\large{%(today)s}}
|
||
\end{titlepage}
|
||
'''
|
||
|
||
def __ModifyMakeTitle(elementskeys,config):
|
||
'''
|
||
如果有maketitle变量则修改maketitle的内容
|
||
:param config: 配置变量
|
||
:return:
|
||
'''
|
||
#得到封面名称
|
||
titlename = config.latex_documents[0][2]
|
||
|
||
if 'releasename' in elementskeys:
|
||
releasename = config.latex_elements['releasename']
|
||
else:
|
||
releasename = ''
|
||
|
||
if hasattr(config,'version'):
|
||
version = config.version
|
||
else:
|
||
version = ''
|
||
release = releasename +' ' + version
|
||
if hasattr(config,'today') and len(config.today) > 0:
|
||
today = config.today
|
||
else:
|
||
todayft = dt.date.today()
|
||
if hasattr(config,'language') and config.language=='zh_CN':
|
||
today = todayft.strftime('%Y 年 %m 月 %d 日')
|
||
else:
|
||
#除中文外，一律用英文时间格式
|
||
#得到英文月的全称。
|
||
month = months[int(todayft.strftime('%m'))-1]
|
||
today = month + todayft.strftime(" %d, %Y")
|
||
|
||
if len(config.latex_elements['maketitle'].strip())==0:
|
||
maketitle = gmaketitle
|
||
else:
|
||
maketitle = config.latex_elements['maketitle']
|
||
#必须转一下，否则赋值不成功
|
||
config.latex_elements['maketitle'] = maketitle % {
|
||
'titlename': titlename,
|
||
'release': release,
|
||
'today': today
|
||
}
|
||
|
||
def config_inited_handler(app, config):
|
||
# 检查年份是否正确，并修改。需配合最新parsejson.py文件使用，否则不支持该接口。
|
||
# 通用配置的修改放在该位置，否则对配置的修改不生效
|
||
try:
|
||
# 该函数的第二个参数可以传入版权声明文件相对于conf.py的相对路径，自动修改版权声明的年份
|
||
# 比如：parsejson.CheckCurrentYearAndModify(app,'../source/copyright/cnperf_conpyright.rst')
|
||
# 默认路径为“./copyright/copyright.rst”和“./copyright/copyright_zh.rst”或者“./copyright/copyright_en.rst”
|
||
# 以上三个路径无需传入
|
||
parsejson.CheckCurrentYearAndModify(app)
|
||
except Exception as e:
|
||
print('------------------')
|
||
print(e)
|
||
# traceback.print_stack()
|
||
traceback.print_exc()
|
||
print('------------------')
|
||
|
||
try:
|
||
# print(sphinx.__version__)
|
||
# app.require_sphinx('3.5')
|
||
keys = config.latex_elements.keys()
|
||
if 'sphinxsetup' not in keys:
|
||
config.latex_elements['sphinxsetup'] = ''
|
||
if "3.5" <= sphinx.__display_version__[:3]:
|
||
config.latex_elements['sphinxsetup'] = 'verbatimforcewraps=true,verbatimmaxunderfull=2,' + \
|
||
config.latex_elements['sphinxsetup']
|
||
if "5.3" <= sphinx.__display_version__[:3]:
|
||
config.latex_table_style = ['standard', 'nocolorrows']
|
||
config.latex_elements['sphinxsetup'] += 'pre_border-radius=0pt,'
|
||
if len(breathe_version) > 0 and "4.3" <= breathe_version:
|
||
config.latex_elements['preamble'] += '''
|
||
\\renewenvironment{description}
|
||
{\\list{}{\\labelwidth=0pt
|
||
\\let\\makelabel\\descriptionlabel}}
|
||
{\\endlist}
|
||
'''
|
||
#如果有自定义maketitle，则修改maketitle的内容
|
||
if 'maketitle' in keys:
|
||
__ModifyMakeTitle(keys,config)
|
||
|
||
# sphinxsetup = config.latex_elements['sphinxsetup']
|
||
# print('sphinxversion:%s;sphinxsetup:%s' % (sphinx.__version__,sphinxsetup))
|
||
except Exception as e:
|
||
# print('sphinxversion:%s %s' % (sphinx.__version__,sphinx.__display_version__[:3]))
|
||
pass
|
||
|
||
|
||
def build_finished_handler(app, exception):
|
||
if exception != None:
|
||
# print(exception)
|
||
return
|
||
|
||
# 判断告警文件是否存在，只有无告警或者告警全是忽略告警才允许继续后续的编译
|
||
if warnfilepath != '' and osp.exists(warnfilepath):
|
||
# 判断告警文件中是否全是忽略告警
|
||
iswarn = parsejson.warn_main(warnfilepath, app)
|
||
if iswarn:
|
||
# 如果为True则说明有不可忽略的告警，报sphinxerror异常，停止继续编译
|
||
raise sperror.SphinxError('There are alarms, please check the file of %s for details' % warnfile)
|
||
return
|
||
|
||
try:
|
||
if app.builder.name == "latex":
|
||
selffnlst = app.config.latex_documents
|
||
parsejson.Modifylatex_main(app.outdir, selffnlst, app)
|
||
except Exception as e:
|
||
print('------------------')
|
||
print(e)
|
||
traceback.print_exc()
|
||
|
||
# 检查html标题一致性。该接口最好放在该位置，主索引文件的标题已经解析出来。
|
||
# if app.builder.name == "html":
|
||
# result = parsejson.CheckProjectNameIsConsistent(app)
|
||
# if result != "":
|
||
# raise sperror.SphinxError(result) #带raise的异常如果用except捕捉，则在终端打印告警将不能显示为红色字体。
|
||
|
||
|
||
def build_inited_handler(app):
|
||
global warnfile
|
||
global warnfilepath
|
||
|
||
print(sys.argv)
|
||
args = sys.argv[1:] # 0为sphinx-build，需忽略掉
|
||
if '-w' in args:
|
||
pos = args.index('-w') # 找到-w所在的索引位置
|
||
warnfile = args[pos + 1] # 得到告警保存的文件名
|
||
# print('warnfile=' + warnfile)
|
||
|
||
# 根据工作路径，得到文件名的绝对路径
|
||
# 当前在build阶段，因此工作路径为Makefile所在的目录，-w后面的文件保存在基于Makefile的相对路径下
|
||
filepath = osp.join(os.getcwd(), warnfile)
|
||
warnfilepath = osp.abspath(filepath)
|
||
# print('warnfilepath = ' + warnfilepath)
|
||
|
||
# try:
|
||
# # 检查是否有rst_prolog或者rst_epilog替换内容，有的话去掉前后空格
|
||
# # 仅适用于pdf文件和中文文档，英文文档和html不启作用
|
||
# checkDocobj = parsejson.clsCheckDocCopyrightYear(app, "")
|
||
# if app.builder.name == 'latex' or app.builder.name == 'latexpdf':
|
||
# checkDocobj.CheckReplaceContent()
|
||
# except Exception as e:
|
||
# print('------------------')
|
||
# print(e)
|
||
# traceback.print_exc()
|
||
# print('------------------')
|
||
|
||
# try:
|
||
# # 检查html配置是否符合规范。必须放在这个位置，否则app没有builder对象。
|
||
# if app.builder.name == "html":
|
||
# error = parsejson.CheckHtmlConfigIsCorrect(app)
|
||
# if error != "":
|
||
# raise sperror.ConfigError(error)
|
||
# except Exception as e:
|
||
# print('------------------')
|
||
# print(e)
|
||
# traceback.print_stack()
|
||
# traceback.print_exc()
|
||
# print('------------------')
|
||
|
||
|
||
def source_read_handler(app, docname, source):
|
||
if cusdirect is not None:
|
||
cnonlyobj = cusdirect.CNOnlyPro(app, docname, source[0])
|
||
source[0] = cnonlyobj.parsecnonlycontent(source[0])
|
||
|
||
# try:
|
||
# 自动添加更新历史代码，默认添加“无内容更新”
|
||
# source[0] = parsejson.CheckUpdateHistory(app, docname, source[0])
|
||
# except Exception as e:
|
||
# print('------------------')
|
||
# print(e)
|
||
# traceback.print_exc()
|
||
# print('------------------')
|
||
|
||
return source
|
||
|
||
|
||
def doctree_resolved_handle(app, doctree, docname):
|
||
"""
|
||
删除不需要文件的内容，避免编译html的时候还进行编译，导致内容泄漏
|
||
"""
|
||
if not hasattr(app.config, 'enable_exclude_html') or not app.config.enable_exclude_html:
|
||
# 默认按sphinx方式编译所有rst文件到html
|
||
return
|
||
|
||
indexname = app.config.master_doc
|
||
if docname == indexname:
|
||
return
|
||
indexdocnames = app.env.toctree_includes[indexname]
|
||
isexist = False
|
||
# 判断文档是否在索引文件里
|
||
if docname not in indexdocnames:
|
||
newtoctree = app.env.toctree_includes.copy()
|
||
del newtoctree[indexname] # 删除主索引文件，因为无需比较
|
||
for key in newtoctree.keys():
|
||
values = newtoctree[key]
|
||
if docname in values:
|
||
isexist = True
|
||
# 判断该key是否在主索引文件里面
|
||
if key not in indexdocnames:
|
||
# 如果不在整个的索引文件里面，删除该文件内容
|
||
# doctree.attributes['source']=''
|
||
while len(doctree.children) > 0:
|
||
doctree.remove(doctree.children[0])
|
||
# 删除标题，否则html页面还有标题，还需要维护标题
|
||
for node in app.env.titles[docname].children:
|
||
app.env.titles[docname].remove(node)
|
||
if not isexist:
|
||
# 文档不在toctree字典里，直接删除内容
|
||
while len(doctree.children) > 0:
|
||
doctree.remove(doctree.children[0])
|
||
# 删除标题，否则html页面还有标题，还需要维护标题
|
||
for node in app.env.titles[docname].children:
|
||
app.env.titles[docname].remove(node)
|
||
|
||
|
||
def setup(app):
|
||
"""
|
||
该函数中的路径都是相对于工程builder环境的路径而不是相对于conf.py所在的路径，
|
||
该函数外面的相对路径是相对于conf.py的路径没有问题。
|
||
比如./_ext相对路径是相对于工程的路径，因此如果使用abspath得到绝对路径会得到~/m0_docs/_ext/,
|
||
而不是~ / mo_docs / source / _ext。
|
||
因此该路径下对路径的判断最好转化为绝对路径判断，否则可能会判断失败。
|
||
:param app:
|
||
:return:
|
||
"""
|
||
app.connect('config-inited', config_inited_handler)
|
||
app.connect('build-finished', build_finished_handler)
|
||
app.connect('builder-inited', build_inited_handler)
|
||
app.connect('source-read', source_read_handler)
|
||
app.connect('doctree-resolved', doctree_resolved_handle)
|
||
|
||
app.add_config_value('chapterbkpaper_image', '', 'env', [str])
|
||
# 是否排除未添加到index的html文件。在编译html时，sphinx默认会将所有rst文件都生成html，因此可能会造成部分内容的泄露。
|
||
# 为了删除这部分内容，设置该变量。如果置为True的话，将删除不在index.rst里面的html的内容。
|
||
# 默认为false，不做处理，以增加编译效率。
|
||
# 建议还是将不参与编译的rst文件，放到exclude_patterns变量内，放到该变量后，rst不参与编译，能提高编译效率。
|
||
app.add_config_value('enable_exclude_html', False, 'env', [bool])
|
||
#配置版权声明文件完整路径，实现版权声明文件年份的自动修改。
|
||
#parsejson.CheckCurrentYearAndModify如果该函数中传入了版权声明的全路径，则以该函数中传入的为准
|
||
#在该处又增加了一个配置值，是为了配置和代码解偶，为了兼容性，保留了原来的配置方式
|
||
app.add_config_value('copyfile_path', '', 'env', [str])
|
||
#在conf.py中配置的conf.json路径，为了实现conf.json配置的灵活处理
|
||
app.add_config_value('confjson_path', '', 'env', [str])
|
||
|
||
if extpathisexist:
|
||
app.setup_extension('customdirective')
|