Running cljdoc locally

Besides development purposes running cljdoc locally can be useful to build documentation for projects without pushing any changes to Clojars and your Git remote.

Here's a step by step instruction to run cljdoc locally and build docs for muuntaja from a local Jar and Git repository:

1. Clone cljdoc

   git clone https://github.com/cljdoc/cljdoc.git
   cd cljdoc/
   

2. Start the cljdoc server

   ./script/cljdoc run
   

   This will start the cljdoc server process, requiring you to open another shell for the following steps.

   Alternatively you can start a REPL with clj, then load the system, move into its namespace and start the server:

   (require '[cljdoc.server.system])
   (in-ns 'cljdoc.server.system)
   (require '[integrant.repl])
   (integrant.repl/set-prep! #(system-config (cfg/config)))
   (integrant.repl/go)
   

3. To build the Javascript files used by the cljdoc pages, run the following in a terminal:

   npm ci                 # reproducibly install packages into node_modules
   npm run format         # format JS code with Prettier
   npm run lint-format    # check if JS code is properly formatted (used in CI)
   npm run build          # production build
   npm run dev            # watch mode
   

   Note: You only need to run build or dev. Usually you would only use dev if you plan on working on JS files.

4. Run tests using Kaocha:

   clj -A:test
   

Importing a Project from Local Sources

1. Clone muuntaja to a directory of your liking and install it into your local Maven repo:

   git clone --branch 0.6.1 https://github.com/metosin/muuntaja.git
   cd muuntaja/
   scripts/lein-modules install
   

   Tip: You can checkout the specific release version instead of 0.6.1. When you do so, remember to change the version number in the command in the next step.

2. Ingest all relevant information into the cljdoc system:

   cd cljdoc/
   ./script/cljdoc ingest -p metosin/muuntaja -v 0.6.1
   

   Or, if you want to specify the jar, pom, git repo and revision explicitly:

   cd cljdoc/
   ./script/cljdoc ingest -p metosin/muuntaja \
                          -v 0.6.1 \
                          --jar ~/.m2/repository/metosin/muuntaja/0.6.1/muuntaja-0.6.1.jar \
                          --pom ~/.m2/repository/metosin/muuntaja/0.6.1/muuntaja-0.6.1.pom \
                          --git /path/to/muuntaja/repo \
                          --rev "master"
   

   Tip: See ./script/cljdoc ingest --help for details.

   Note: For Git-based changes to take effect you need to commit them so there is a revision that the repo can be analysed at. This can be done in a branch of course.

3. Open the docs for muuntaja on the local cljdoc server: http://localhost:8000/d/metosin/muuntaja

---

Thats pretty much it! Stop by on Slack if you have any problems. :wave: