Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

json-object lexer (JsonBareObjectLexer) description lacks detail #1600

Closed
j1elo opened this issue Nov 11, 2020 · 9 comments
Closed

json-object lexer (JsonBareObjectLexer) description lacks detail #1600

j1elo opened this issue Nov 11, 2020 · 9 comments
Milestone

Comments

@j1elo
Copy link

@j1elo j1elo commented Nov 11, 2020

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
Copy link
Contributor

@birkenfeld birkenfeld commented Nov 11, 2020

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.

@Anteru Anteru added this to the 2.7.3 milestone Nov 11, 2020
@j1elo
Copy link
Author

@j1elo j1elo commented Nov 11, 2020

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
Copy link
Contributor

@birkenfeld birkenfeld commented Nov 11, 2020

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

@Anteru
Copy link
Collaborator

@Anteru Anteru commented Nov 11, 2020

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

@birkenfeld
Copy link
Contributor

@birkenfeld birkenfeld commented Nov 11, 2020

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
Copy link
Author

@j1elo j1elo commented Nov 12, 2020

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.

j1elo added a commit to Kurento/doc-kurento that referenced this issue Nov 12, 2020
Given comments in pygments/pygments#1600, the
json-object lexer is geting deprecated with the upcoming Pygments 2.8,
and will fall back to "json".

At the same time, Pygments 2.8 comes with a new JSON parser that allows
for partial blocks missing surrounding curly braces, which is exactly
the use case we have in this documentation. Nice update!
@Anteru
Copy link
Collaborator

@Anteru Anteru commented Nov 13, 2020

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

@birkenfeld
Copy link
Contributor

@birkenfeld birkenfeld commented Nov 13, 2020

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

@Anteru
Copy link
Collaborator

@Anteru Anteru commented Nov 13, 2020

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

j1elo added a commit to Kurento/doc-kurento that referenced this issue Nov 13, 2020
Given comments in pygments/pygments#1600, the
json-object lexer is geting deprecated with the upcoming Pygments 2.8,
and will fall back to "json".

At the same time, Pygments 2.8 comes with a new JSON parser that allows
for partial blocks missing surrounding curly braces, which is exactly
the use case we have in this documentation. Nice update!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants