You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
``snippet-fmt`` is configured using the ``pyproject.toml`` file in the root of your project
6
6
(alongside ``setup.py``, ``tox.ini`` etc.).
7
-
The file uses the `TOML <https://github.com/toml-lang/toml>`_ syntax,
7
+
The file uses the TOML_ syntax,
8
8
with the configuration in the ``[tool.snippet-fmt]`` table.
9
9
10
-
The table can contain two keys: :ref:`hooks <snippet_fmt_toml_languages>`
11
-
and :ref:`config <snippet_fmt_toml_directives>`
10
+
The table can contain two keys: :tconf:`languages` and :tconf:`directives`
12
11
13
12
Alternatively, the :option:`-c / --config-file <snippet-fmt -c>` option can be used to point to a different TOML file.
14
13
The layout is the same except the table ``[snippet-fmt]`` rather than ``[tool.snippet.fmt]``.
15
14
16
15
17
-
.. _snippet_fmt_toml_languages:
16
+
.. tconf:: languages
18
17
19
-
``languages``
20
-
--------------
18
+
This is a table of tables giving languages to check and reformat.
21
19
22
-
This is a list of languages to check and reformat.
20
+
These correspond to the value after ``.. code-block::``, preserving case.
23
21
24
-
These correspond to the value after ``.. code-block::``, ignoring case.
22
+
For example, the following codeblock has a value of ``'TOML'``:
25
23
26
-
For example, the following codeblock has a value of ``'toml'``:
24
+
.. code-block:: rst
27
25
28
-
.. code-block:: rst
26
+
.. code-block:: TOML
29
27
30
-
.. code-block:: TOML
28
+
key = "value"
31
29
32
-
key = "value"
30
+
Each language has a corresponding check / reformat function,
31
+
which is determined from the lowercased form of the language name.
32
+
This allows certain code blocks in a language to be excluded from formatting
33
+
by using a different case, such as using ``TOML`` for most code blocks
34
+
and ``toml`` for ones which shouldn't be reformatted.
33
35
34
36
35
-
The currently supported languages are:
37
+
The currently supported languages (matched case insensitively) are:
36
38
37
-
* JSON -- syntax check only.
38
-
* INI -- syntax check only.
39
-
* TOML -- syntax check only, v0.5.0.
40
-
* Python / Python3 -- syntax check and reformatting using formate_.
39
+
* JSON
40
+
* INI
41
+
* TOML
42
+
* Python / Python3
41
43
42
-
Defaults to ``['python', 'toml', 'ini', 'json']``.
44
+
Each sub table contains options specific to that language (and capitalisation).
45
+
The exact options vary, but each has a ``reformat`` option which defaults to :py:obj:`False`.
46
+
If set to :py:obj:`True` the code snippets in that language will be reformatted,
47
+
otherwise they will only be syntax checked.
43
48
44
-
.. _formate: https://formate.readthedocs.io
49
+
By default all languages are enabled for checks only.
50
+
51
+
52
+
.. tconf:: directives
53
+
54
+
The directive types to reformat, such as ``'code-block'`` for ``.. code-block::``.
55
+
56
+
The values are case sensitive.
57
+
58
+
Defaults to ``['code', 'code-block', 'sourcecode']``.
59
+
60
+
61
+
Supported Languages
62
+
-------------------------
63
+
64
+
The following languages are supported by ``snippet-fmt``:
65
+
66
+
67
+
Python / Python3
68
+
^^^^^^^^^^^^^^^^^^^^
69
+
70
+
Reformatting Python_ files with formate_.
71
+
72
+
73
+
:bold-title:`Options`
74
+
75
+
.. tconf:: python.reformat
76
+
:type::toml:`Boolean`
77
+
:default: False
78
+
79
+
If set to ``true`` the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.
80
+
81
+
82
+
.. tconf:: python.config-file
83
+
:type::toml:`String`
84
+
:default: formate.toml
85
+
86
+
The TOML_ file containing the configuration for formate_.
87
+
88
+
.. TODO:: link for formate's docs
89
+
90
+
91
+
JSON
92
+
^^^^^^^^
93
+
94
+
Syntax checking and reformatting of JSON files, using Python's :mod:`json` module.
95
+
96
+
97
+
:bold-title:`Options`
98
+
99
+
.. tconf:: json.reformat
100
+
:type::toml:`Boolean`
101
+
:default: False
102
+
103
+
If set to ``true`` the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.
104
+
105
+
106
+
.. tconf:: json.ensure_ascii
107
+
:type::toml:`Boolean`
108
+
:default: false
109
+
110
+
If ``true``, the output is guaranteed to have all incoming non-ASCII characters escaped. If ``false`` (the default), these characters will be output as-is.
45
111
112
+
.. tconf:: json.allow_nan
113
+
:type::toml:`Boolean`
114
+
:default: true
46
115
47
-
.. _snippet_fmt_toml_directives:
116
+
If ``true`` (the default), then ``NaN``, ``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.
48
117
49
-
``directives``
50
-
----------------
118
+
.. note:: JSON snippets containing ``NaN`` etc. when this option is ``false`` and ``reformat`` is also ``false`` will pass, as this check only takes place durinh reformatting.
51
119
52
-
The directive types to reformat, such as ``'code-block'`` for ``.. code-block::``.
53
120
54
-
The values are case sensitive.
121
+
.. tconf:: json.sort_keys
122
+
:type::toml:`Boolean`
123
+
:default: false
55
124
56
-
Defaults to ``['code', 'code-block', 'sourcecode']``.
125
+
If ``true`` then the keys will be sorted alphabetically.
126
+
127
+
128
+
.. tconf:: json.indent
129
+
:type::toml:`Integer` or :toml:`string`
130
+
131
+
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.
132
+
133
+
134
+
.. tconf:: json.separators
135
+
:type::toml:`Array` of :toml:`string`
136
+
137
+
A 2-element array of ``[item_separator, key_separator]``.
138
+
The default is ``(', ', ': ')`` if ``indent`` is unspecified and ``(',', ': ')`` otherwise.
139
+
To get the most compact JSON representation, you should specify ``(',', ':')`` to eliminate whitespace.
140
+
141
+
142
+
TOML
143
+
^^^^^^^^
144
+
145
+
Syntax checking and reformatting of TOML_ files using the `toml <https://pypi.org/project/toml>`__ library.
146
+
147
+
.. note:: This only supports TOML_ version `0.5.0 <https://toml.io/en/v0.5.0>`_.
148
+
149
+
150
+
:bold-title:`Options`
151
+
152
+
.. tconf:: toml.reformat
153
+
:type::toml:`Boolean`
154
+
:default: False
155
+
156
+
If set to ``true`` the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.
157
+
158
+
159
+
INI
160
+
^^^^^^^^
161
+
162
+
Syntax checking and reformatting of INI files, using Python's :mod:`configparser` module.
163
+
164
+
165
+
:bold-title:`Options`
166
+
167
+
.. tconf:: ini.reformat
168
+
:type::toml:`Boolean`
169
+
:default: False
170
+
171
+
If set to ``true`` the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.
57
172
58
173
59
174
Example
@@ -62,5 +177,27 @@ Example
62
177
.. code-block:: toml
63
178
64
179
[tool.snippet-fmt]
65
-
languages = ['python', 'toml', 'ini']
66
180
directives = ['code', 'code-block', 'sourcecode']
181
+
182
+
[tool.snippet-fmt.languages.python]
183
+
reformat = true
184
+
config-file = "pyproject.toml"
185
+
186
+
[tool.snippet-fmt.languages.TOML]
187
+
reformat = true
188
+
189
+
[tool.snippet-fmt.languages.toml]
190
+
[tool.snippet-fmt.languages.ini]
191
+
192
+
This will:
193
+
194
+
* look at ``.. code::``, ``.. code-block::`` and ``.. sourcecode::`` directives
195
+
for ``python``, ``TOML``, ``toml``, and ``ini``.
196
+
* Code blocks marked ``python`` and ``TOML`` will be reformatted.
197
+
* Code blocks marked ``toml`` and ``ini`` will only be checked for valid syntax.
198
+
* formate_ is configured to take its configuration from ``pyproject.toml``.
0 commit comments