doc: contribute: guidelines: Document KeepSorted and options #101197
Conversation
Allow making the zephyr-keep-sorted check ignore cases, for example: // zephyr-keep-sorted-start ignorecase .... // zephyr-keep-sorted-stop Signed-off-by: Pieter De Gendt <[email protected]>
Use the directive to create an actual link to the check_compliance.py file. Signed-off-by: Pieter De Gendt <[email protected]>
pdgendt
force-pushed
the
keep-sorted-doc
branch
from
66141ca to
312b31c
Compare
doc/contribute/guidelines.rst
Outdated
| The KeepSorted check ensures that specified blocks of code, configuration, or | ||
| documentation remain in sorted order. | ||
|
|
||
| To use the KeepSorted check, wrap your sorted content with marker comments: |
There was a problem hiding this comment.
Could be a bit more explicit about zephyr-keep-sorted-{start,stop} being the magic marker, and the "comment" just being needed so that the file remains valid.
Something like:
| To use the KeepSorted check, wrap your sorted content with marker comments: | |
| To use the KeepSorted check, wrap your sorted content between a dedicated line containing | |
| start marker ``zephyr-keep-sorted-start`` and a dedicated line containing end marker | |
| ``zephyr-keep-sorted-end`` (usually, these marker lines will be comments): |
There was a problem hiding this comment.
We can't put these inline as they would be picked up by the compliance script 😆
There was a problem hiding this comment.
oh right 😭 - but maybe we can keep something like this without the actual markers then?
| `casefold https://docs.python.org/3/library/stdtypes.html#str.casefold`_. This allows | ||
| mixing uppercase and lowercase items in sorted blocks without causing sort | ||
| order violations. | ||
|
|
There was a problem hiding this comment.
I'd provide a simple example with only one option:
Options are provided on the same line as the start marker. For example, the following
<ensures only lines matching regexp will be sorted>:
zephyr-keep-sorted-start re(........)
xxxx
yyyy
zephyr-keep-sorted-end
There was a problem hiding this comment.
The regex option has an example already?
There was a problem hiding this comment.
I took regexp as an example but it could be anything. As you said, there are examples already, so this is a bit silly... but the current wording feels a bit rough:
The KeepSorted start marker supports several optional parameters to
customize the sorting behavior:
See new review comment for alternative proposal.
pdgendt
force-pushed
the
keep-sorted-doc
branch
2 times, most recently
from
f68a8af to
139951d
Compare
doc/contribute/guidelines.rst
Outdated
| The KeepSorted start marker supports several optional parameters to | ||
| customize the sorting behavior: |
There was a problem hiding this comment.
cont. of #101197 (comment)
| The KeepSorted start marker supports several optional parameters to | |
| customize the sorting behavior: | |
| The sorting behavior of each block can be customized in several ways. | |
| To do this, one or more of the following parameters can be added on | |
| the same line as the start marker itself: |
Add a documentation section about the KeepSorted compliance check and which options it provides. Signed-off-by: Pieter De Gendt <[email protected]>
pdgendt
force-pushed
the
keep-sorted-doc
branch
from
139951d to
14bbe6e
Compare
|
2 participants
Add a documentation about the
KeepSortedcompliance check and which options it provides.Depends on #101188