//: # ({:display :header, :valid-structure? true, :rendered-params ({:display :summary, :model :onyx.gen-doc/lein-plugin, :format :h6} {:display :attribute-table, :model :onyx.gen-doc/lein-plugin, :columns [[:key "Key"] [:type "Type"] [:doc "Description"]]} {:display :catalog-entry, :model :onyx.gen-doc/lein-plugin, :merge-additions {:in-path "README.template.md", :out-path "README.md", :verbose? true, :throw? :onyx.gen-doc/ignore}} {:display :summary, :model :onyx.gen-doc/summary-template, :format :h6} {:display :attribute-table, :model :onyx.gen-doc/summary-template, :columns [[:key "Key"] [:type "Type"] [:optional? "Optional?" :code] [:doc "Description"] [:choices "Choices" :code]]} {:display :catalog-entry, :model :onyx.gen-doc/summary-template, :view-source? true, :merge-additions {:format-string "The summary: %s"}} {:display :summary, :model :onyx.gen-doc/attribute-table-template, :format :h6} {:display :attribute-table, :model :onyx.gen-doc/attribute-table-template, :columns [[:key "Key"] [:type "Type"] [:optional? "Optional?" :code] [:doc "Description"]]} {:display :catalog-entry, :model :onyx.gen-doc/attribute-table-template, :view-source? true} {:display :summary, :model :onyx.gen-doc/catalog-entry-template, :format :h6} {:display :attribute-table, :model :onyx.gen-doc/catalog-entry-template, :columns [[:key "Key"] [:type "Type"] [:optional? "Optional?" :code] [:doc "Description"]]} {:display :catalog-entry, :model :onyx.gen-doc/catalog-entry-template, :view-source? true, :merge-additions {:in-this-model :overridden, :not-in-this-model :added, :ignore-in-this-model :onyx.gen-doc/ignore}} {:display :summary, :model :onyx.gen-doc/lifecycle-entry-template, :format :h6} {:display :attribute-table, :model :onyx.gen-doc/lifecycle-entry-template, :columns [[:key "Key"] [:type "Type"] [:optional? "Optional?" :code] [:doc "Description"]]} {:display :catalog-entry, :model :onyx.gen-doc/lifecycle-entry-template, :view-source? true})}) //: # (✔ All catalog entries documented.) //: # (✔ All lifecycle entries documented.)

onyx-doc-gen

Utilities for rendering Onyx information model data into a Markdown template. Comprises a Leiningen plugin and a core library. Use this system to keep an Onyx plugin's documentation in sync with its respective information model.

Installation

In the plugin project file :dependencies:

[org.onyxplatform/onyx-gen-doc "0.9.12-SNAPSHOT"]

In the plugin project file :plugins:

[org.onyxplatform/lein-onyx-gen-doc "0.9.12-SNAPSHOT"]

Note that the root lein project, org.onyxplatform/onyx-gen-doc-doc is used to generate this documentation. It does not need to be installed in the target plugin project.

Plugin configuration

Leiningen plugin options for :onyx-doc-gen in the target project.clj.

Key	Type	Description
:information-model	:symbol	The fully-qualified symbol of the information model. Must be on the target classpath.
:in-path	:string	The template file path.
:out-path	:string	The output file path.
:verbose?	:boolean	In the output file, includes processed template data, inline as markdown comments.
:throw?	:boolean	Throws first exception into the lein process, instead of serializing all exception into output inline comments.

Example onyx-gen-doc: value: //: # ({:display :catalog-entry, :model :onyx.gen-doc/lein-plugin, :merge-additions {:in-path "README.template.md", :out-path "README.md", :verbose? true, :throw? :onyx.gen-doc/ignore}})

{:information-model my.ns/information-model,
 :in-path "README.template.md",
 :out-path "README.md",
 :verbose? true}

See this repository's root project.clj for a contextual example.

Templates

This readme is itself generated from templates. Compare the raw source of README.template.md to see templates in action.

Summary template

Prints the catalog entry summary.

Key	Type	Optional?	Description	Choices
:display	:keyword		The keyword :summary
:model	:keyword		The catalog entry key.
:format	:keyword	true	Apply a Markdown format.	[:plain :h1 :h2 :h3 :h4 :h5 :h6 :code :clojure :em :strong]
:format-string	:string	true	Applies clojure.core/format with this value, to the summary.

    ```onyx-gen-doc
    {:display :summary,
     :model :my.ns/model,
     :format :plain,
     :format-string "The summary: %s"}
    ```

Attribute table template

A table of the catalog entry attributes.

Key	Type	Optional?	Description
:display	:keyword		The keyword :attribute-table
:model	:keyword		The catalog entry key.
:columns	:keyword-or-vector	true	A vector of column specs or a keyword specifying a config preset.

    ```onyx-gen-doc
    {:display :attribute-table,
     :model :my.ns/model,
     :columns :columns/default}
    ```

Catalog entry template

An example catalog entry. Values are naïvely inferred. Use :merge-additions to clarify.

Key	Type	Optional?	Description
:display	:keyword		The keyword :catalog-entry
:model	:keyword		The catalog entry key.
:merge-additions	:map	true	Overrides and additions merged into the example catalog entry. To elide a model entry, use :onyx.gen-doc/ignore as the value for the ignored key.

    ```onyx-gen-doc
    {:display :catalog-entry,
     :model :my.ns/model,
     :merge-additions
     {:in-this-model :overridden,
      :not-in-this-model :added,
      :ignore-in-this-model :onyx.gen-doc/ignore}}
    ```

Lifecycle entry template

A lifecycle entry.

Key	Type	Optional?	Description
:display	:keyword		The keyword :lifecycle-entry
:model	:keyword		The lifecycle entry key.

    ```onyx-gen-doc
    {:display :lifecycle-entry, :model :my.ns/model}
    ```