Skip to content

Utilities for rendering Onyx information model data into a Markdown template

Notifications You must be signed in to change notification settings

onyx-platform/onyx-gen-doc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

29 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

//: # ({: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}
    ```

About

Utilities for rendering Onyx information model data into a Markdown template

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published