生成部分sphinx文件的Python代码是可能的吗？ [英] Python code to generate part of sphinx documentation, is it possible?

问题描述

我正在使用狮身人面像来生成矿山项目的文档。

I am using sphinx to generate the documentation for a project of mines.

在这样的项目中，我将在 yaml 文件中描述可用命令的列表，一旦加载，就会得到一个表单 {command-name：command-description} 的字典，例如：

In such project, I describe a list of available commands in a yaml file which, once loaded, results in a dictionary in the form {command-name : command-description} for example:

commands = {"copy"  : "Copy the highlighted text in the clipboard",
            "paste" : "Paste the clipboard text to cursor location",
            ...}

我想知道的是如果在sphinx中有一个方法在 make html 循环中加载yaml文件，以某种 reStructuredText 格式翻译python字典（例如，定义列表），并包含在我的html输出中。

What I would like to know, is if there is a method in sphinx to load the yaml file during the make html cycle, translate the python dictionary in some reStructuredText format (e.g. a definition list) and include in my html output.

我希望我的 .rst 文件看起来像：

I would expect my .rst file to look like:

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之前。

before being translated to html.

提前感谢您的时间和专长！

Thank you in advance for your time and expertise!

推荐答案

最后我找到了一种实现我想要的方式。以下是操作方法：

At the end I find a way to achieve what I wanted. Here's the how-to:

1. 创建一个python脚本（让我们称之为 generate -includes.py ），将生成 reStructuredText 并将其保存在 myrst.inc 文件中。 （在我的例子中，这将是脚本加载和解析YAML，但这是无关紧要的）。确保这个文件是可执行的!!!



2. 使用 include

1. Create a python script (let's call it generate-includes.py) that will generate the reStructuredText and save it in the myrst.inc file. (In my example, this would be the script loading and parsing the YAML, but this is irrelevant). Make sure this file is executable!!!

2. Use the include directive in your main .rst document of your documentation, in the point where you want your dynamically-generated documentation to be inserted:

.. include:: myrst.inc

修改sphinx Makefile ，以便在构建时生成所需的.inc文件：

Modify the sphinx Makefile in order to generate the required .inc files at build time:

myrst.inc:
    ./generate-includes.py

html: myrst.inc
    ...(other stuff here)

通常使用 make html 。

这篇关于生成部分sphinx文件的Python代码是可能的吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！