hydrox, Parkside Style

dive deeper into your code

Installation

Deps Project:

1. In your deps.edn, make a new gen-docs alias with hydrox and the old version of core.match (used by hydrox to parse html):

 :aliases {
           :gen-docs  {:extra-deps
                      {parkside-securities/hydrox  {:mvn/version "0.10.5"}
                       org.clojure/core.match      {:mvn/version  "0.2.2"}}
           }

2. Create the :documentation map in your deps.edn. This is how Hydrox knows where to put generated documents:

:documentation {:site   "test-docs"
                 :output "docs"
                 :template {:path "template"
                            :copy ["assets"]
                            :defaults {:template     "article.html"
                                       :navbar       [:file "partials/navbar.html"]
                                       :dependencies [:file "partials/deps-web.html"]
                                       :navigation   :navigation
                                       :article      :article}}
                 :paths ["test"]
                 :files {"test-docs-name"
                         {:input "test/your_app/docs_test.clj"
                          :title "Your App Tests"
                          :subtitle "change these for your app."}}}}

3. Create the docs folder in your project. Intialize with a docs/.gitignore that includes the following lines:

*
*/
!.gitignore
# docs contents are generated by hydrox and copied to docker image at runtime 
# generated artifacts shouldn't be checked into git in general.

4. Create the template folder and copy the templates and assets from this project into it so the documentation generator can access them and they will have a standardized look.

5. Set up the server for your new files as follows:

• If you do not already have the latest pedestal in your project, add it to deps.edn, then add to your project according to the pedestal README.
• In your config.edn, configure pedestal to include a :file-path like so:

:pedestal/service {:service-map  #ig/ref :your-app.pedestal/service
                   :interceptors [whatever the interceptors already were if you've got 'em']
                   :dev?         #duct/env "PEDESTAL_SERVICE_DEV"
                   :file-path    "docs"}

6. Open the repl with clj -A:dev:gen-docs -e "(dev)(go)" -r

7. In the repl run:

(generate-docs)

If you have correctly formatted your :documentation map, docs should be generated into your docs folder! If you have correctly set up your pedestal server, you should be able to see the docs at localhost:PORT/test-docs-name.html!

8. Once it looks good, add the docs generation step to the project's wercker.yml:

 - script:
        name: generate docs
        code: clojure -A:dev:gen-docs -e "(dev)(generate-docs)"

Lein Project:

In your project.clj, add hydrox to the [:profiles :dev :dependencies] entry:

(defproject ...
  ...
  :plugins ["lein-hydrox" "0.1.15"]
  :profiles {:dev {:dependencies [...
                                  [helpshift/hydrox "0.1.15"]
                                  ...]}}
  ...)

Leiningen

To initialise a project:

lein hydrox init

To generate documentation (watches project for changes and updates documentation accordingly):

lein hydrox

Original-flavor Hydrox Tutorials

• 0 - Introduction
• 1 - Getting Started

Overview

hydrox assists in the transmission of knowledge around a clojure project, providing in-repl management of documentation, docstrings and metadata through the reuse/repurposing of test code. The tool allows for a design-orientated workflow for the programming process, blurring the boundaries between design, development, testing and documentation.

Please see the docs for more information (generated using itself).

Links and References:

• the generated website for hara can be seen here

• the .html output can be seen for a sample .clj input

License

Copyright © 2015 Helpshift

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.