由于 json 指针，Sphinx 无法包含我的 JSON 定义文件

Question

我正在记录我的 JSON 架构，使用 Sphinx 将其托管在 ReadTheDocs 上。

当我在主模式文件中有我的定义时，一切都很好。但我想将我的定义移动到外部 json 文件。

我的代码更改自

"$ref": "#/definitions/positiveNumber"

到

"$ref": "./general.definitions.json#/definitions/positiveNumber"

我的 general.definitions.json 文件如下所示：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/andrejellema/GlobalCoffeeDataStandard/master/schema/general.definitions.json",
  "title": "General definitions",
  "definitions": {
    "percentage": {
      "title": "The percentage, 0-100",
      "description": "The percentage, from 0 to 100 with decimals allowed",
      "$comment": "Duplicate in /productionCosts.json",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "positiveNumber": {
      "title": "A positive number > 0",
      "description": "A positive number starting at 0 with decimals allowed",
      "type": "number",
      "minimum": 0
    },
    "greaterThanZero": {
      "title": "The positive number, greater than 0",
      "description": "A positive number starting at greater than 0 with decimals allowed",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "yesNo": {
      "title": "Yes-No enumeration",
      "type": "string",
      "enum": [
        "Yes",
        "No"
      ]
    }
  }
}

我的第一个失败内容：

.. literalinclude:: ../../schema/general.definitions.json#/definitions/positiveNumber
   :language: json
   :linenos:
   :caption: Object description

我的第一个有效内容：

.. literalinclude:: ../../schema/global-unique-id.json
   :language: json
   :linenos:
   :caption: Object description

当我调用 make html 时出现此错误：

[...]\docs\source\explanation.rst:1360: WARNING: Include file '[...]\schema\general.definitions.json#\definitions\positiveNumber' not found or reading it failed

文件存在于该位置。似乎 Sphinx 没有正确处理 JSON 指针。

我该怎么做才能解决这个问题？

Answer 1

Sphinx 不理解JSON 指针语法。

为了突出显示包含的 JSON 文件中的特定行，您可以使用 :emphasize-lines: 选项。示例：

.. literalinclude:: ./general.definitions.json
   :language: json
   :linenos:
   :emphasize-lines: 14
   :caption: Object description

由于 json 指针，Sphinx 无法包含我的 JSON 定义文件

Sphinx cannot include my JSON definition file due to json pointers

json

python-sphinx

jsonschema

jsonpointer