Sphinx cannot include my JSON definition file due to json pointers

Question

I'm documenting my JSON Schema using Sphinx to host it on ReadTheDocs.

When I have my definitions in my main schema file all is well. But I want to move my definitions to an external json file.

My code changes from

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

to

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

My general.definitions.json file looks like this:

{
  "$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"
      ]
    }
  }
}

My rst-content that fails:

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

My rst-content that works:

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

When I call make html I get this error:

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

The file exists on that location. It seems Sphinx doesn't handle the JSON pointer correctly.

What can I do to solve this?

" or reading it failed". Check its permissions to make sure it is readable. Also post the reST snippet that includes the file. — Steve Piercy, Feb 14 '19 at 18:40
Thanks @StevePiercy I've updated my post and added my snippits — Paul Meems, Feb 15 '19 at 08:09
Sphinx does not understand JSON Pointer. What output do you expect? Perhaps you can use `:emphasize-lines: 14` to highlight the line with "positiveNumber" (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude). — mzjn, Feb 15 '19 at 08:30
Thanks @mzjn I'll go that route. Can you repost your comment as an answer so I can mark it as such? — Paul Meems, Feb 15 '19 at 09:38

score 2 · Accepted Answer · answered Feb 15 '19 at 10:01

Sphinx does not understand JSON Pointer syntax.

In order to highlight a certain line in the included JSON file, you can use the :emphasize-lines: option. Example:

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

Sphinx cannot include my JSON definition file due to json pointers

1 Answers1