nextstrain / docs.nextstrain.org

Umbrella documentation project for Nextstrain
https://docs.nextstrain.org
18 stars 13 forks source link

Fix code block highlighting issues #15

Closed eharkins closed 2 years ago

eharkins commented 4 years ago

Some documents from submodules have code blocks with special syntax highlighting for certain types of files / languages. Read the docs doesn't recognize some of them, so if we want to have this formatting work in read the docs / sphinx, we'll need to find a solution for this, whether by removing the highlighting, using an existing solution like a plugin for sphinx, or writing a custom script.

Low priority since it just results in warnings and the rendered code blocks are still readable.

E.g. from current docs build of this repo:

/Users/eharkins/nextstrain/docs.nextstrain.org/src/ncov/docs/customizing-analysis.md: WARNING: Pygments lexer name 'tsv' is not known
/Users/eharkins/nextstrain/docs.nextstrain.org/src/ncov/docs/customizing-visualization.md: WARNING: Could not lex literal_block as "json". Highlighting skipped.
/Users/eharkins/nextstrain/docs.nextstrain.org/src/ncov/docs/customizing-visualization.md: WARNING: Could not lex literal_block as "json". Highlighting skipped.
/Users/eharkins/nextstrain/docs.nextstrain.org/src/ncov/docs/customizing-visualization.md: WARNING: Could not lex literal_block as "json". Highlighting skipped.
sachin-suresh-rapyuta commented 2 years ago

Any fix for this?

tsibley commented 2 years ago

Those ncov docs have undergone a lot of overhauling since this issue was created, including conversion from Markdown to rST.

The JSON examples are now correctly highlighted using .. code:: json blocks in rST. But note that the original issue reported here wasn't that json wasn't a recognized language, but that lexing it failed (i.e. the JSON was probably invalid).

The TSV examples are simply not marked with a language anymore. This seems fine to me, as it's not clear to me what exactly would be highlighted for a TSV anyway.

Closing as this is no longer an issue.