json-object lexer (JsonBareObjectLexer) description lacks detail

[j1elo]

This report accompanies the other one at #1599 regarding a lexer which its user docs are lacking detail that helps understand even what the lexer is intended for.

In this case, the json-object docs state "For JSON data structures (with missing object curly braces)" (JsonBareObjectLexer) but a bit more in-depth information and even a usage sample would do lots in term of helping to understand the feature.

I have a JSON file (here, regardless of how good or bad decision it was to choose JSON for user-editable configuration... JSON is used for historical reasons) of which I want to document a small section (see here for the actual case).

I tried using json-object like this, under the assumption that it would work because that's what I'm able to understand from "with missing object curly braces":

.. code-block:: json-object

   "secure": {
     "port": 8433,
     "certificate": "cert+key.pem",
     "password": "KEY_PASSWORD"
   }

but it fails parsing and Sphinx warns about it:

security.rst:152: WARNING: Could not lex literal_block as "json-object". Highlighting skipped.

Curiously enough, this valid JSON also fails:

.. code-block:: json-object

   {
     "secure": {
       "port": 8433,
       "certificate": "cert+key.pem",
       "password": "KEY_PASSWORD"
     }
   }

The Sphinx warning is the same as before.

(and nevertheless I'd like to avoid putting the additional braces to make it JSON-compliant, because it would add noise and might drive users to think they should somehow write the setting under a new, independent object)

This probably is just a silly misunderstanding like what happened in #1599 so a bit more extended docs would probably help a lot.

[birkenfeld]

Even I have no idea what JsonBareObjectLexer was supposed to do.

However, in the current master it is simply the same as JsonLexer and we should deprecate it.

[j1elo]

Thank you.

Maybe the intention for JsonBareObjectLexer was precisely to support use cases such as the one I mentioned? I.e. provide a JSON object without the enclosing braces? If so it would be an interesting feature. Perhaps someone had a nice idea about it and was going to contribute the code but in the end it never got into master. I'd understand that, happens all the time.

[birkenfeld]

That use case is already supported by JsonLexer in 2.7 - it highlights that snippet without errors.

[Anteru]

@birkenfeld Did you also test on master, given that has a new JsonLexer (for perf)?

[birkenfeld]

Well when I said 2.7 I meant master - I had thought the new JsonLexer was already in 2.7. If not, make it 2.8 :)

[j1elo]

I confirmed this is in master but not in 2.7; and, confirmed too that the JSON parser in master allows the mentioned use case. After pip-installing from master, all warnings from Sphinx disappeared, very nice! Thanks for the comments and the useful updates.

[Anteru]

The new JSON parser should go out in 2.7.3; I haven't merged anything yet which would warrant 2.8.

[birkenfeld]

Ok, then you'll need to move around the changelog entry.

[Anteru]

I've been training all my life for this day :)