Liking cljdoc? Tell your friends :D

Developer Guide

Audience

Thanks for your interest test-doc-blocks development.

Prerequisites

Generalities

We make use of babashka tasks. To see a list of available tasks, run:

bb tasks

For help on a task’s available command line arguments, run bb <task-name> --help, for example:

bb lint --help

Testing

Unit

bb test-unit

Integration

Run integration test via:

bb test-integration

This will:

  1. generate tests for code blocks within test-doc-block docs

  2. then diff against a previously manually verified test run

The previously verified test run is under test-resources/expected.

You’ll need to carefully manually inspect any failures. Inspection can be a bit tedious and annoying, particularly when only line numbers have changed. Bear with it. When you are confident the generated results are correct:

bb gen-to-expected

And commit/push the expected results.

Generated

Generate then run tests under Clojure via:

bb test-gen-kaocha

Or

bb test-gen-clj

Generate then run tests under ClojureScript via:

bb test-gen-cljs

Reminder: test generation itself always happens under Clojure.

Checking for Outdated Dependencies

To see if there are new versions of dependencies available, run:

bb outdated

Linting

We use clj-kondo to lint the project source and fail the build when linting fails.

To run linting as the CI server does:

bb lint

If you want to rebuild the lint cache, use the --rebuild option.

Continuous Integration

To run what CI runs:

bb ci-test

This task includes verification that test-doc-blocks works as expected under all supported versions of Clojure.

Docs

Format

When possible, documentation is in AsciiDoc. We follow AsciiDoc best practice of one sentence per line.

We use GitHub’s CommonMark only when necessary to illustrate, test and document CommonMark features.

Testing

Code blocks in our docs are, naturally, tested by test-doc-blocks. See testing section for details.

Example docs

We describe inline features in:

Keep in mind that example.adoc and example.md will, by design, describe the same features and, except where there are AsciiDoc vs CommonMark differences, have the same text. It is a burden keeping these docs in synch, but worth it for the end user who is likely only using either AsciiDoc or CommonMark.

These documents are also run through our test suite to test the features they describe.

Contributors

We honor contributors in our README file. To update contributors, update doc/contributors.edn and then run:

bb doc-update-readme

Cljdoc Preview

Before a release, it can be comforting to preview what docs will look like on cljdoc.

Limitations

  • Considered this task experimental. I have tested on macOS and Linux. I’m not sure about Windows at this time.

  • You have to push your changes to GitHub to preview them. This allows for a full preview that includes any links (source, images, etc.) to GitHub. This task works fine from branches and forks - if you don’t want to affect your main development branch for a preview.

Start Local Services

To start the local cljdoc docker container:

bb cljdoc-preview start

The local cljdoc server lets you view your ingested docs in your web browser.

The start command also automatically checks docker hub for any updates so that our cljdoc preview matches the current production version of cljdoc.

Ingest Docs

To ingest rewrite-clj API and docs into the local cljdoc database:

bb cljdoc-preview ingest

The ingest command automatically publishes rewrite-clj to your local maven repository (cljdoc only works with published jars).

The locally published version will include a -cljdoc-preview suffix. This distinction helps to reduce confusion about locally vs remotely installed artifacts.

You’ll have to remember to git commit and git push your changes before ingesting.

Repeat these steps any time you want to preview changes.

Preview Docs

To open a view to the ingested docs in your default web browser:

bb cljdoc-preview view

If you have just run the start command, be a bit patient; the cljdoc server can take a few moments to start up - especially on macOS due to poor file-sharing performance.

Stop Local Services

When done, you’ll want to stop your docker container:

bb cljdoc-preview stop

This will also delete temporary files created to support your preview session, most notably the local cljdoc database.

Note that NO cleanup is done for any rewrite-clj artifacts published to your local maven repository.

Container Status

If you forget where you are at with your docker containers, run:

bb cljdoc-preview status

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

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

× close