diff options
| -rw-r--r-- | doc/contributing.rst | 66 | ||||
| -rw-r--r-- | doc/docstyle.rst | 9 |
2 files changed, 51 insertions, 24 deletions
diff --git a/doc/contributing.rst b/doc/contributing.rst index 39a44fb2b..a4baaef05 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -18,15 +18,23 @@ See `codeowners <codeowners.html>`_ for more details. Writing tests ============= -There are 3 types of tests: +There are 4 types of tests: 1. ``runnableExamples`` documentation comment tests, ran by ``nim doc mymod.nim`` These end up in documentation and ensure documentation stays in sync with code. -2. tests in ``when isMainModule:`` block, ran by ``nim c mymod.nim`` - ``nimble test`` also typially runs these in external nimble packages. +2. separate test files, e.g.: ``tests/stdlib/tos.nim``. + In nim repo, `testament` (see below) runs all `$nim/tests/*/t*.nim` test files; + for nimble packages, see https://github.com/nim-lang/nimble#tests. -3. testament tests, e.g.: ``tests/stdlib/tos.nim`` (only used for Nim repo). +3. (deprecated) tests in ``when isMainModule:`` block, ran by ``nim r mymod.nim``. + ``nimble test`` can run those in nimble packages when specified in a + `task "test"`. + +4. (not preferred) `.. code-block:: nim` RST snippets; these should only be used in rst sources, + in nim sources `runnableExamples` should now always be preferred to those for + several reasons (cleaner syntax, syntax highlights, batched testing, and + `rdoccmd` allows customization). Not all the tests follow the convention here, feel free to change the ones that don't. Always leave the code cleaner than you found it. @@ -34,31 +42,43 @@ that don't. Always leave the code cleaner than you found it. Stdlib ------ -If you change the stdlib (anything under ``lib/``, e.g. ``lib/pure/os.nim``), -put a test in the file you changed. Add the tests under a ``when isMainModule:`` -condition so they only get executed when the tester is building the -file. Each test should be in a separate ``block:`` statement, such that +Each stdlib module (anything under ``lib/``, e.g. ``lib/pure/os.nim``) should +preferably have a corresponding separate test file, eg `tests/stdlib/tos.nim`. +The old convention was to add a ``when isMainModule:`` block in the source file, +which only gets executed when the tester is building the file. + +Each test should be in a separate ``block:`` statement, such that each has its own scope. Use boolean conditions and ``doAssert`` for the -testing by itself, don't rely on echo statements or similar. +testing by itself, don't rely on echo statements or similar; in particular avoid +things like `echo "done"`. Sample test: .. code-block:: nim - when isMainModule: - block: # newSeqWith tests - var seq2D = newSeqWith(4, newSeq[bool](2)) - seq2D[0][0] = true - seq2D[1][0] = true - seq2D[0][1] = true - doAssert seq2D == @[@[true, true], @[true, false], - @[false, false], @[false, false]] - # doAssert with `not` can now be done as follows: - doAssert not (1 == 2) - -Newer tests tend to be run via ``testament`` rather than via ``when isMainModule:``, -e.g. ``tests/stdlib/tos.nim``; this allows additional features such as custom -compiler flags; for more details see below. + block: # bug #1234 + static: doAssert 1+1 == 2 + + block: # bug #1235 + var seq2D = newSeqWith(4, newSeq[bool](2)) + seq2D[0][0] = true + seq2D[1][0] = true + seq2D[0][1] = true + doAssert seq2D == @[@[true, true], @[true, false], + @[false, false], @[false, false]] + # doAssert with `not` can now be done as follows: + doAssert not (1 == 2) + +Always refer to a github issue using the following exact syntax: `bug #1234` as shown +above, so that it's consistent and easier to search or for tooling. Some browser +extensions (eg https://github.com/sindresorhus/refined-github) will even turn those +in clickable links when it works. + +Rationale for using a separate test file instead of `when isMainModule:` block: +* allows custom compiler flags or testing options (see details below) +* faster CI since they can be joined in `megatest` (combined into a single test) +* avoids making the parser do un-necessary work when a source file is merely imported +* avoids mixing source and test code when reporting line of code statistics or code coverage Compiler -------- diff --git a/doc/docstyle.rst b/doc/docstyle.rst index f0785bc0a..70ded0689 100644 --- a/doc/docstyle.rst +++ b/doc/docstyle.rst @@ -4,10 +4,17 @@ Documentation Style General Guidelines ------------------ +* See also `nep1<https://nim-lang.github.io/Nim/nep1.html>`_ which should probably be merged here. * Authors should document anything that is exported; documentation for private procs can be useful too (visible via ``nim doc --docInternal foo.nim``). -* Within documentation, a period (`.`) should follow each sentence (or sentence fragment) in a comment block. The documentation may be limited to one sentence fragment, but if multiple sentences are within the documentation, each sentence after the first should be complete and in present tense. +* Within documentation, a period (`.`) should follow each sentence (or sentence fragment) in a comment block. + The documentation may be limited to one sentence fragment, but if multiple sentences are within the documentation, + each sentence after the first should be complete and in present tense. * Documentation is parsed as a custom ReStructuredText (RST) with partial markdown support. +* In nim sources, prefer single backticks to double backticks since it's simpler + and `nim doc` supports it (even in rst files with `nim rst2html`). +* In nim sources, for links, prefer `[link text](link.html)` to ``` `link text<link.html>`_ ``` + since the syntax is simpler and markdown is more common (likewise, `nim rst2html` also supports it in rst files). .. code-block:: nim |