Configuration¶
snippet-fmt
is configured using the pyproject.toml
file in the root of your project
(alongside setup.py
, tox.ini
etc.).
The file uses the TOML syntax,
with the configuration in the [tool.snippet-fmt]
table.
The table can contain two keys: languages
and directives
Alternatively, the -c / --config-file
option can be used to point to a different TOML file.
The layout is the same except the table [snippet-fmt]
rather than [tool.snippet.fmt]
.
-
languages
¶ This is a table of tables giving languages to check and reformat.
These correspond to the value after
.. code-block::
, preserving case.For example, the following codeblock has a value of
'TOML'
:.. code-block:: TOML key = "value"
Each language has a corresponding check / reformat function, which is determined from the lowercased form of the language name. This allows certain code blocks in a language to be excluded from formatting by using a different case, such as using
TOML
for most code blocks andtoml
for ones which shouldn’t be reformatted.The currently supported languages (matched case insensitively) are:
JSON
INI
TOML
Python / Python3
Each sub table contains options specific to that language (and capitalisation). The exact options vary, but each has a
reformat
option which defaults toFalse
. If set toTrue
the code snippets in that language will be reformatted, otherwise they will only be syntax checked.By default all languages are enabled for checks only.
-
directives
¶ The directive types to reformat, such as
'code-block'
for.. code-block::
.The values are case sensitive.
Defaults to
['code', 'code-block', 'sourcecode']
.
Supported Languages¶
The following languages are supported by snippet-fmt
:
Python / Python3¶
Reformatting Python files with formate.
Options
JSON¶
Syntax checking and reformatting of JSON files, using Python’s json
module.
Options
-
json.
reformat
¶ - Type: BooleanDefault: False
If set to
true
the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.
-
json.
ensure_ascii
¶ - Type: BooleanDefault: false
If
true
, the output is guaranteed to have all incoming non-ASCII characters escaped. Iffalse
(the default), these characters will be output as-is.
-
json.
allow_nan
¶ - Type: BooleanDefault: true
If
true
(the default), thenNaN
,Infinity
, and-Infinity
will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise an error will be raised when attepting to reformat files containing such floats.Note
JSON snippets containing
NaN
etc. when this option isfalse
andreformat
is alsofalse
will pass, as this check only takes place durinh reformatting.
-
json.
indent
¶ -
If
indent
is a non-negative integer or string, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0, negative, or “” will only insert newlines. If not specified a compact representation will be used. Using a positive integer indent indents that many spaces per level. If indent is a string (such as “t”), that string is used to indent each level.
-
json.
separators
¶ -
A 2-element array of
[item_separator, key_separator]
. The default is(', ', ': ')
ifindent
is unspecified and(',', ': ')
otherwise. To get the most compact JSON representation, you should specify(',', ':')
to eliminate whitespace.
Example¶
[tool.snippet-fmt]
directives = [ "code", "code-block", "sourcecode",]
[tool.snippet-fmt.languages.python]
reformat = true
config-file = "pyproject.toml"
[tool.snippet-fmt.languages.TOML]
reformat = true
[tool.snippet-fmt.languages.toml]
[tool.snippet-fmt.languages.ini]
This will:
look at
.. code::
,.. code-block::
and.. sourcecode::
directives forpython
,TOML
,toml
, andini
.Code blocks marked
python
andTOML
will be reformatted.Code blocks marked
toml
andini
will only be checked for valid syntax.formate is configured to take its configuration from
pyproject.toml
.