Python 3.x 斯芬克斯文档和降价链接
我试图使用Sphinx从Markdown源代码构建一些文档。我的Python 3.x 斯芬克斯文档和降价链接,python-3.x,markdown,python-sphinx,Python 3.x,Markdown,Python Sphinx,我试图使用Sphinx从Markdown源代码构建一些文档。我的conf.py如下所示 conf.py from recommonmark.parser import CommonMarkParser project = 'DS' copyright = '2018, DS' author = 'DS, Work' version = '' release = '' extensions = [] templates_path = ['_templates'] source_suffix
conf.py
如下所示
conf.py
from recommonmark.parser import CommonMarkParser
project = 'DS'
copyright = '2018, DS'
author = 'DS, Work'
version = ''
release = ''
extensions = []
templates_path = ['_templates']
source_suffix = ['.rst', '.md']
master_doc = 'index'
language = None
exclude_patterns = []
pygments_style = 'sphinx'
html_theme = 'classic'
html_static_path = ['_static']
source_parsers = {
'.md': CommonMarkParser,
}
htmlhelp_basename = 'DSDocumentationdoc'
latex_elements = {
}
latex_documents = [
(master_doc, 'DSDocumentation.tex', 'DS Documentation',
'DS, Work', 'manual'),
]
man_pages = [
(master_doc, 'dsdocumentation', 'DS Documentation',
[author], 1)
]
texinfo_documents = [
(master_doc, 'DSDocumentation', 'DS Documentation',
author, 'DSDocumentation', 'One line description ofproject.',
'Miscellaneous'),
]
index.rst
Welcome to DS Documentation!
======================================
The following documentation is produced and maintained by the Data Science team.
Contents:
.. toctree::
:maxdepth: 2
:glob:
README.md
documentation.md
getting_started/*
how-tos/*
statistics_data_visualisation.md
文档生成和html输出是生成的,但是README.md
在两个子目录中有指向其他标记文档的链接,如以下
... [this document](./getting_started/setting_your_machine_up.md)...
…在翻译后的README.html
文档中,目标尚未转换为翻译后的html目标,因为其已被识别为参考外部
...<a class="reference external" href="./getting_started/setting_your_machine_up.md">this document</a>...
def setup(app):
app.add_config_value('recommonmark_config', {
'enable_auto_doc_ref': True,
}, True)
app.add_transform(AutoStructify)
…因此,链接的工作方式与侧边栏中的目录相同
对于是否能够实现这一目标的任何建议,我们将不胜感激
干杯
编辑
尝试@waylan建议的解决方案,我已通过conf.py
将以下内容添加到enable\u auto\u doc\u ref
...<a class="reference external" href="./getting_started/setting_your_machine_up.md">this document</a>...
def setup(app):
app.add_config_value('recommonmark_config', {
'enable_auto_doc_ref': True,
}, True)
app.add_transform(AutoStructify)
…在运行makehtml
时,我得到以下错误
❱ cat /tmp/sphinx-err-57rejer3.log
# Sphinx version: 1.8.0
# Python version: 3.6.6 (CPython)
# Docutils version: 0.14
# Jinja2 version: 2.10
# Last messages:
# building [mo]: targets for 0 po files that are out of date
#
# building [html]: targets for 16 source files that are out of date
#
# updating environment:
#
# 16 added, 0 changed, 0 removed
#
# reading sources... [ 6%] README
#
# Loaded extensions:
# sphinx.ext.mathjax (1.8.0) from /home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/ext/math
jax.py
# alabaster (0.7.11) from /home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/alabaster/__init__.py
Traceback (most recent call last):
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/cmd/build.py", line 304, in build_ma
in
app.build(args.force_all, filenames)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/application.py", line 341, in build
self.builder.build_update()
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 347, in
build_update
len(to_build))
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 360, in
build
updated_docnames = set(self.read())
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 468, in
read
self._read_serial(docnames)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 490, in
_read_serial
self.read_doc(docname)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 534, in
read_doc
doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/io.py", line 318, in read_doc
pub.publish()
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/docutils/core.py", line 218, in publish
self.apply_transforms()
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/docutils/core.py", line 199, in apply_trans
forms
self.document.transformer.apply_transforms()
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/sphinx/transforms/__init__.py", line 90, in
apply_transforms
Transformer.apply_transforms(self)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/docutils/transforms/__init__.py", line 171,
in apply_transforms
transform.apply(**kwargs)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 325, in ap
ply
self.traverse(self.document)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 297, in tr
averse
self.traverse(child)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 297, in tr
averse
self.traverse(child)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 297, in tr
averse
self.traverse(child)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 287, in tr
averse
newnode = self.find_replace(c)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 267, in fi
nd_replace
newnode = self.auto_doc_ref(node)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/transform.py", line 175, in au
to_doc_ref
return self.state_machine.run_role('doc', content=content)
File "/home/neil.shephard@samba.sheffield.thefloow.com/.local/lib/python3.6/site-packages/recommonmark/states.py", line 134, in run_r
ole
content=content)
TypeError: 'NoneType' object is not callable
我已经查看了最后两个调用,我认为这可能是由于未设置内容,这可能与我的index.rst
有关,但我在这里真的没有深度。建议通过将以下内容添加到config.py
文件来启用:
from recommonmark.transform import AutoStructify
github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
这将为您提供以下功能:
- 启用自动目录树:是否启用自动目录树功能
- 自动目录树章节:启用后,自动目录树将仅在与标题匹配的章节上启用
- 启用自动文档参考:是否启用自动文档参考功能
- 启用数学:是否启用数学公式
- 启用内联数学:是否启用内联数学
- 启用\u评估\u rst:是否启用嵌入重构文本
- url\u解析器:将文档中现有的相对位置映射到http链接的函数
值得注意的是:
在一个文档中引用另一个文档页面是很常见的。我们
通常使用引用来实现这一点。AutoStructify将转换这些
将参照块转换为结构化文档参照。比如说
[API Reference](api_ref.md)
将被转换为以下重新构造的文本代码的AST
:doc:`API Reference </api_ref>`
:doc:`API参考`
它将被呈现为API引用
为什么这是必要的?因为,与Rst不同,Markdown不了解给定文档之外的任何内容,也不支持Rst样式的指令。因此,没有转换URL的机制
相反,AutoStructify会等到RecomonMarkBridge将标记转换为Sphinx的底层文档结构(docutils文档对象)之后,再运行一系列转换器,以提供有限的类似Rst的功能。即使使用AutoStructify,在使用降价时也永远无法获得完整的功能支持。这将需要降价以获得对指令的本机支持,这是不可能发生的。建议通过将以下内容添加到config.py
文件中来启用:
from recommonmark.transform import AutoStructify
github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
这将为您提供以下功能:
- 启用自动目录树:是否启用自动目录树功能
- 自动目录树章节:启用后,自动目录树将仅在与标题匹配的章节上启用
- 启用自动文档参考:是否启用自动文档参考功能
- 启用数学:是否启用数学公式
- 启用内联数学:是否启用内联数学
- 启用\u评估\u rst:是否启用嵌入重构文本
- url\u解析器:将文档中现有的相对位置映射到http链接的函数
值得注意的是:
在一个文档中引用另一个文档页面是很常见的。我们
通常使用引用来实现这一点。AutoStructify将转换这些
将参照块转换为结构化文档参照。比如说
[API Reference](api_ref.md)
将被转换为以下重新构造的文本代码的AST
:doc:`API Reference </api_ref>`
:doc:`API参考`
它将被呈现为API引用
为什么这是必要的?因为,与Rst不同,Markdown不了解给定文档之外的任何内容,也不支持Rst样式的指令。因此,没有转换URL的机制
相反,AutoStructify会等到RecomonMarkBridge将标记转换为Sphinx的底层文档结构(docutils文档对象)之后,再运行一系列转换器,以提供有限的类似Rst的功能。即使使用AutoStructify,在使用降价时也永远无法获得完整的功能支持。这将需要降价来获得指令的本地支持,这是不可能发生的。@slackline我添加了一个解释,解释了为什么Autostructif是必要的,并概述了它的工作原理。非常感谢花时间解释所有这些@Waylan(在开始新工作后,我只使用Python 4.5个月).在尝试您的建议时,我遇到了一个错误,我在上面的原始帖子中详细介绍了这个错误。我刚刚编辑了我的答案,以包括来自RecomonMark.transform import AutoStructify
。我希望这会解决您的问题。我在RecomonMark上读到,AutoStructify
需要显式导入,所以我已经这样做了包含在conf.py
的标题中,很抱歉没有将其包含在上面的编辑中。我再次查看了这一点,并在recommonmark上发现enable\u auto\u doc\u ref
现在已被弃用(请参阅,在GitHub repos上也被标记为这样)。它建议“标记中的链接默认添加为:any:role,