(chapter-start 'html-help “Utilities for generating html-formatted documentation”)

(def helpful/chapters/path (chapter-name)

; override this to customise for your own application's routes
"/dox/chapters/~chapter-name")

(def helpful/items/path (item-name)

; override this to customise for your own application's routes
"/dox/items/~(percent-encode item-name)")

(defmemo helpful/chapters/index ()

; return a HTML table element with a row for each chapter. Each row provides a link to the chapter,
; the chapter descripton, and chapter content names
(%table.chapters
        (mapx (sort (chapter-names)) chap
              (%tr (%td (%a(href (helpful/chapters/path chap)) chap))
                   (let chapter (chapter-find chap)
                     (j (%td chapter.description)
                        (%td (joinstr "\n"
                                      (map λi(%a.item(href (helpful/items/path i.name)) (hesc i.name))
                                           chapter.contents)))))))))

(defmemo helpful/chapters/show (chapter-name)

; return a HTML div element containing a paragraph for the chapter description, and a table element
; containing  a row for each item. Each item row provides a link to the item, the item type, and
; the item documentation
(let chapter (chapter-find chapter-name)
  (%div (%p chapter.description)
        (%table.chapter-items
                (mapx (sort-by &name chapter.contents) item-group
                      (mapx item-group item
                            (%tr(class (rowclass))
                                (%td item.what)
                                (%td (%a.item(href (helpful/items/path item.name)) item.name))
                                (%td (render-as-textile (joinstr "\n" item.texts))))))))))

; generate html to present documentation for a 'def or a 'mac (def helpful/item/def (item)

(%div.item-info
      (%h4 (%span.type item.what) " "
           (%span.name item.name) " "
           (%span.small.args (inspect item.args)))
      (%p.small "Defined in " (%b (inspect item.file)) " in plugin " (%b (inspect item.plugin)))
      (%p
       (j:map λc(%a.chapter(href (helpful/chapters/path c)) c) item.chapters)
       (render-as-textile (joinstr "\n" item.texts)))
      (%h4 "Source")
      (%pre.source (preserve:hesc:dox-show-src item.src))))

; generate html documentation for a setting (def helpful/item/setting (item)

(%div.item-info
   (%h4 (%span.type item.setting.context) " " (%span.name item.name))
   (%p (j:map λc(%a.chapter(href (helpful/chapters/path c)) c) item.chapters)
       (render-as-textile (joinstr "\n" item.texts)))
  (%h4 "Current value (evaluated)")
  (%pre.source:setting item.setting.name)
  (%h4 "Definitions and sources")
  (%table.setting-values (settings/values/help item.values))))

(assign helpful/handlers

{
 def     helpful/item/def
 mac     helpful/item/def
 setting helpful/item/setting
})

(def helpful/item/info (item)

((hash-get helpful/handlers item.what) item))

(def helpful/item/example (example)

(%div.item-example
      (%h5 "example: " (%b (car example)))
      (%pre.source (preserve:hesc:dox-show-src:cadr example))
      (%pre.source (preserve:hesc:dox-show-src:caddr example))))

(defmemo helpful/item (item-name)

; return a HTML div element with lots of information about the named item
(with (items    (dox-lookup item-name)
       examples (dox-examples item-name))
  (%div.items-info
        (j:map λi(helpful/item/info i) items)
        (%h4 "Examples")
        (j:map λx(map λy(helpful/item/example y) x) examples))))

; show history of setters for this item (def settings/values/help (values)

(map-inline values val
  (%tr (%td val.plugin) (%td val.script) (%td (%pre.source:preserve:hesc:dox-show-src val.value)))))

; show history of setters for item with given name, except for initial default value (def settings/values (name) (aif (dox-item-by-type 'setting (sym name)) (settings/values/help (all-but-last it.values))))

; generate html documentation for the setting with the given name (def settings/help (name) (settings/help/item (dox-item-by-type 'setting (sym name))))