Developer Guide

Run integration test via:

This will:

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:

And commit/push the expected results.

Generate then run tests under Clojure via:

Or

Generate then run tests under ClojureScript via:

Reminder: test generation itself always happens under Clojure.

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.

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

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.

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

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

Limitations

Start Local Services

To start the local cljdoc docker container:

The local cljdoc server allows you to 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:

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. I find this distinction helps to reduce confusion around 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:

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:

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: