我正在使用Sphinx为我的项目生成文档。
在这个项目中,我描述了yaml文件中的可用命令列表,一旦加载,就会生成{command-name : command-description}
形式的字典,例如:
commands = {"copy" : "Copy the highlighted text in the clipboard",
"paste" : "Paste the clipboard text to cursor location",
...}
我想知道的是,如果sphinx中有一个方法在make html
周期内加载yaml文件,则以某些 reStructuredText 格式翻译python字典(例如definition list)并包含在我的html输出中。
我希望我的.rst
文件看起来像:
Available commands
==================
The commands available in bla-bla-bla...
.. magic-directive-that-execute-python-code::
:maybe python code or name of python file here:
并在内部转换为:
Available commands
==================
The commands available in bla-bla-bla...
copy
Copy the highlighted text in the clipboard
paste
Paste the clipboard text to cursor location
在被翻译成HTML之前。
答案 0 :(得分:21)
最后,我找到了实现我想要的方法。这是方法:
generate-includes.py
),它将生成 reStructuredText 并将其保存在myrst.inc
文件中。 (在我的例子中,这将是加载和解析YAML的脚本,但这是无关紧要的)。 确保此文件可执行!!! 在文档的主要.rst文档中使用include
指令,以便插入动态生成的文档:
.. include:: myrst.inc
修改sphinx Makefile ,以便在构建时生成所需的.inc文件:
myrst.inc:
./generate-includes.py
html: myrst.inc
...(other stuff here)
使用make html
正常构建文档。
答案 1 :(得分:14)
基于迈克尔代码和内置include指令的改进:
import sys
from os.path import basename
try:
from StringIO import StringIO
except ImportError:
from io import StringIO
from sphinx.util.compat import Directive
from docutils import nodes, statemachine
class ExecDirective(Directive):
"""Execute the specified python code and insert the output into the document"""
has_content = True
def run(self):
oldStdout, sys.stdout = sys.stdout, StringIO()
tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
source = self.state_machine.input_lines.source(self.lineno - self.state_machine.input_offset - 1)
try:
exec('\n'.join(self.content))
text = sys.stdout.getvalue()
lines = statemachine.string2lines(text, tab_width, convert_whitespace=True)
self.state_machine.insert_input(lines, source)
return []
except Exception:
return [nodes.error(None, nodes.paragraph(text = "Unable to execute python code at %s:%d:" % (basename(source), self.lineno)), nodes.paragraph(text = str(sys.exc_info()[1])))]
finally:
sys.stdout = oldStdout
def setup(app):
app.add_directive('exec', ExecDirective)
这个先前输入输出,以便直接通过解析器。它也适用于Python 3.
答案 2 :(得分:8)
我需要同样的东西,所以我把一个似乎有效的新指令汇总在一起(我对自定义Sphinx指令一无所知,但到目前为止它已经工作了):
import sys
from os.path import basename
from StringIO import StringIO
from sphinx.util.compat import Directive
from docutils import nodes
class ExecDirective(Directive):
"""Execute the specified python code and insert the output into the document"""
has_content = True
def run(self):
oldStdout, sys.stdout = sys.stdout, StringIO()
try:
exec '\n'.join(self.content)
return [nodes.paragraph(text = sys.stdout.getvalue())]
except Exception, e:
return [nodes.error(None, nodes.paragraph(text = "Unable to execute python code at %s:%d:" % (basename(self.src), self.srcline)), nodes.paragraph(text = str(e)))]
finally:
sys.stdout = oldStdout
def setup(app):
app.add_directive('exec', ExecDirective)
使用如下:
.. exec::
print "Python code!"
print "This text will show up in the document"
答案 3 :(得分:4)
Sphinx没有任何内置功能可以做你喜欢的事情。您可以创建自定义指令来处理文件,也可以在单独的步骤中生成reStructuredText,并使用include指令包含生成的reStructuredText文件。
答案 4 :(得分:2)
我知道这个问题很老,但也许其他人会发现它也很有用。
听起来你实际上并不需要执行任何python代码,但你只需要重新格式化文件的内容。在这种情况下,您可能需要查看sphinx-jinja(https://pypi.python.org/pypi/sphinx-jinja)。
您可以在conf.py
:
jinja_contexts = yaml.load(yourFileHere)
然后你可以使用jinja模板来写出内容并将它们视为reST输入。
答案 5 :(得分:0)
Sphinx支持自定义扩展,这可能是执行此操作的最佳方式http://sphinx.pocoo.org/ext/tutorial.html。