jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

enable syntax highlighting for inline code (#17585)

Browse source 
* enable syntax highlighting for inline code

* finish '.. default-role' and preliminary '.. role'

implementation

* more compact check in dirRole

* set :literal: as default role for *.rst

* Update lib/packages/docutils/rst.nim

Co-authored-by: Timothee Cour <timothee.cour2@gmail.com>

* use whichRole for setting currRoleKind

* Update lib/packages/docutils/rst.nim

Co-authored-by: Timothee Cour <timothee.cour2@gmail.com>

* rename rnGeneralRole -> rnUnknownRole

Co-authored-by: Timothee Cour <timothee.cour2@gmail.com>
This commit is contained in:
Andrey Makarov 2021-04-02 23:11:44 +03:00 • committed by GitHub
commit e35946f306
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 239 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

38
doc/contributing.rst
View file

@ -295,6 +295,44 @@ example below) from `Nim Index`_ can be used in doc comment this way:
.. _`Nim Index`: https://nim-lang.org/docs/theindex.html
Inline monospaced text can be input using \`single backticks\` or
\`\`double backticks\`\`. The former are syntactically highlighted,
the latter are not.
To avoid accidental highlighting follow this rule in `*.nim` files:
* use single backticks for fragments of code in Nim and other
programming languages, including identifiers, in `*.nim` files.
For languages other than Nim add a role after final backtick,
e.g. for C++ inline highlighting::
`#include <stdio.h>`:cpp:
For a currently unsupported language add the `:code:` role,
like for SQL in this example::
`SELECT * FROM <table_name>;`:code:
* prefer double backticks otherwise:
* for file names: \`\`os.nim\`\`
* for fragments of strings **not** enclosed by `"` and `"` and not
related to code, e.g. text of compiler messages
* for command line options: \`\`--docInternal\`\`
* also when code ends with a standalone ``\`` (otherwise a combination of
``\`` and a final \` would get escaped)
.. Note:: `*.rst` files have `:literal:` as their default role.
So for them the rule above is only applicable if the `:nim:` role
is set up manually as the default::
.. role:: nim(code)
:language: nim
.. default-role:: nim
The first 2 lines are for other RST implementations,
including Github one.
Best practices
==============