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. Build the Javascript files used by the cljdoc pages:

   npm ci                 # reproducibly install packages into node_modules
   npm run format         # format JS code with Prettier
   npm run build          # production build
   

   Check that resources-compiled folder was generated.

   If you plan to work on JS files, instead of npm run build run dev:

   npm ci                 # reproducibly install packages into node_modules
   npm run format         # format JS code with Prettier
   npm run dev            # watch mode
   

3. 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)
   

4. (Optional) 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 --git /path/to/muuntaja/repo
   

   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: