Liking cljdoc? Tell your friends :D

lread.test-doc-blocks

Test Clojars cljdoc

Test AsciiDoc and CommonMark code blocks found in articles and docstrings.

Example code in docs, while likely not malicious, could be illustrating, for example, how to wipe a drive. So, do be deliberate and careful about what docs you run through test-doc-blocks.

Status

Initial concept. Currently being used to test doc blocks in rewrite-clj.

  • Working very well for rewrite-clj, might work for other projects too.

  • Feedback welcome.

Rationale

I wanted to make sure the code examples I provided in rewrite-clj v1 documentation do not mislead and do function as expected for those who dare to try them. You might want the same for your library.

Versioning

Test-doc-block versioning scheme is: major.minor.patch-test-qualifier

  • major increments when the API has been broken - something, as a rule, we’d like to avoid.

  • minor increments to convey significant new features have been added.

  • patch indicates bug fixes - it is the number of commits in the repo.

  • test-qualifier is absent for stable releases. Can be alpha, beta, rc1, etc.

License

Copyright © 2021 Lee Read, all rights reserved.

Distributed under the EPL License, same as Clojure. See LICENSE.

Concept based on @seancorfield’s readme which is distributed under EPL v1.0 or later.

Can you improve this documentation? These fine people already did:
lread & GitHub Actions
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close