mirror of
https://github.com/HiPhish/rainbow-delimiters.nvim.git
synced 2024-09-08 02:25:48 +02:00
Update documentation
This commit is contained in:
parent
a1773953fc
commit
e85bc80b44
2 changed files with 68 additions and 0 deletions
54
HACKING.rst
54
HACKING.rst
|
@ -57,6 +57,60 @@ To run tests the `g:bustedprg` variable must be set to `'./test/busted'`, which
|
|||
is the path to the shim script. If the `exrc` option is set the variable will
|
||||
be set automatically.
|
||||
|
||||
Highlight testing
|
||||
=================
|
||||
|
||||
Highlights are tested by comparing the current highlights of a sample file with
|
||||
previously recorded highlights known to be correct. Of course this does
|
||||
nothing when defining new patterns or making changes to a sample file; in this
|
||||
case a human has to initially approve of the highlighting. Once that is done
|
||||
the current state can be recorded. Automated highlighting tests are useful
|
||||
when making changes to the highlighting logic itself to ensure the results
|
||||
remain unchanged.
|
||||
|
||||
Execute `make highlight-test` to run highlighting tests.
|
||||
|
||||
Definitions
|
||||
-----------
|
||||
|
||||
Sample file
|
||||
A file in the language we want to highlight. The contents have to be
|
||||
syntactically correct, and ideally the file should compile, but it does not
|
||||
have to make sense. Sample files are stored under an arbitrary name
|
||||
(although `regular` is the most common) in `test/highlight/samples/<lang>`.
|
||||
|
||||
Specification or spec
|
||||
A Lua file which records all rainbow delimiter extmarks for a given
|
||||
combination of sample file and query. Why Lua? It could have been JSON,
|
||||
but generating nicely formatted Lua was simpler, that's all. Each spec is
|
||||
just a table, there is no logic.
|
||||
|
||||
Recording
|
||||
The act of reading a sample file, extracting all highlighting information
|
||||
and writing it to a spec. You could write all the specs by hand, but there
|
||||
is a helper function for that instead.
|
||||
|
||||
|
||||
Recording highlighting
|
||||
----------------------
|
||||
|
||||
First make the necessary changes to the sample file or query. Then call the
|
||||
`record_extmarks` function from the `rainbow-delimiters._test.highlight`
|
||||
module. This module is not part of the runtime plugin code, so it is
|
||||
undocumented. The function takes three optional arguments (all strings):
|
||||
|
||||
- `language`: The language in question
|
||||
- `sample`: Name of the sample file
|
||||
- `query`: Name of the query
|
||||
|
||||
If any one of these is missing the specs for all applicable languages, samples
|
||||
or queries are recorded. You should at least specify the language, otherwise
|
||||
the function can take a lot of time.
|
||||
|
||||
|
||||
Running highlight tests
|
||||
-----------------------
|
||||
|
||||
|
||||
|
||||
Design decisions
|
||||
|
|
|
@ -22,6 +22,7 @@ TABLE OF CONTENTS *rb-delimiters-contents*
|
|||
3.2 Custom queries ........................ |rb-delimiters-custom-query|
|
||||
3.3 Custom strategies ..................... |rb-delimiters-custom-strategy|
|
||||
3.4 Adding new languages .................. |rb-delimiters-custom-lang|
|
||||
3.5 Adding highlight tests ................ |rb-delimiters-highlight-test|
|
||||
4. Recipes ................................... |rb-delimiters-recipes|
|
||||
5. Acknowledgements .......................... |rb-delimiters-credit|
|
||||
6. Further reading ........................... |rb-delimiters-reading|
|
||||
|
@ -699,6 +700,19 @@ language. If the query is mature enough please consider upstreaming it so
|
|||
everyone can benefit.
|
||||
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
ADDING HIGHLIGHT TESTS *rb-delimiters-highlight-test*
|
||||
|
||||
Whenever you make changes to a query or add support for a new language you
|
||||
should also add highlighting tests if you want to upsteam your changes. There
|
||||
are two steps:
|
||||
|
||||
- Add a sample file to show off the highlighting
|
||||
- Record the state of highlighting
|
||||
|
||||
See the `CONTRIBUTING` file of this repository for details.
|
||||
|
||||
|
||||
==============================================================================
|
||||
RECIPES *rb-delimiters-recipes*
|
||||
|
||||
|
|
Loading…
Reference in a new issue