cljdoc.doc-tree
Process doctrees provided by projects via a doc/cljdoc.edn file.
Projects can provide a tree of articles via the :cljdoc.doc/tree key.
The data that's provided via this key roughly follows the familiar Hiccup format:
[["Readme" {:file "Readme.md"}
["Child Of Readme" {:file "child.md"}]]]
Reading the files that are specified in this tree is outside of the
concern of this namespace and handled via a passed-in function slurp-fn.
Usually this function will read the specified file from a Git repository
at a specified revision. This was done to keep this namespace free of any
Git/IO-related aspects.
The return format is described in the ::doctree spec that's part of this namespace.
There also is some additional code derive-toc that will return a
doctree based on a list of files. This is used to derive the doctree
for projects that haven't provided one explicitly.
Process doctrees provided by projects via a `doc/cljdoc.edn` file.
Projects can provide a tree of articles via the `:cljdoc.doc/tree` key.
The data that's provided via this key roughly follows the familiar Hiccup format:
[["Readme" {:file "Readme.md"}
["Child Of Readme" {:file "child.md"}]]]
Reading the files that are specified in this tree is outside of the
concern of this namespace and handled via a passed-in function `slurp-fn`.
Usually this function will read the specified file from a Git repository
at a specified revision. This was done to keep this namespace free of any
Git/IO-related aspects.
The return format is described in the `::doctree` spec that's part of this namespace.
There also is some additional code `derive-toc` that will return a
doctree based on a list of files. This is used to derive the doctree
for projects that haven't provided one explicitly.add-slug-pathclj
(add-slug-path doc-tree)(add-slug-path doc-tree base)For various purposes it is useful to know the path to a given document in it's doc tree. This function adds a field in [:attrs :slug-path] that contains the slug of the current document preceded by all slugs of documents above it in the tree.
Probably this could be implemented better using zippers or similar.
For various purposes it is useful to know the path to a given document in it's doc tree. This function adds a field in [:attrs :slug-path] that contains the slug of the current document preceded by all slugs of documents above it in the tree. Probably this could be implemented better using zippers or similar.
derive-tocclj
(derive-toc files)Given a list of files (as strings) return a doctree that can be
passed to process-toc. By default this function will return a
doctree consisting of the project's Readme and Changelog as well as
other files in doc/ or docs/.
Only files written in supported formats (Markdown or Asciidoc) will be taken into account during this process.
Given a list of `files` (as strings) return a doctree that can be passed to `process-toc`. By default this function will return a doctree consisting of the project's Readme and Changelog as well as other files in `doc/` or `docs/`. Only files written in supported formats (Markdown or Asciidoc) will be taken into account during this process.
entry->type-and-contentclj
(entry->type-and-content doctree-entry)Given a single doctree entry return a tuple with the type of the to be rendered document and it's content. This is a layer of indirection to enable backwards compatibility with doctrees that do not contain a :cljdoc.doc/type key.
Given a single doctree entry return a tuple with the type of the to be rendered document and it's content. This is a layer of indirection to enable backwards compatibility with doctrees that do not contain a :cljdoc.doc/type key.
filepath->typecljmultimethod
An extension point for custom doctree items. Dispatching is done based on file extensions. The return value is used for two things:
- It's stored as
:cljdoc.doc/typein the doctree entry map - The contents of a file will be stored at the returned value
See [[process-toc-entry]] for the specifics.
NOTE: I find a multimethod not perfectly appropriate here but it's straightforward to extend from other artifacts and - for now - gets the job done.
An extension point for custom doctree items. Dispatching is done based on file extensions. The return value is used for two things: - It's stored as `:cljdoc.doc/type` in the doctree entry map - The contents of a file will be stored at the returned value See [[process-toc-entry]] for the specifics. NOTE: I find a multimethod not perfectly appropriate here but it's straightforward to extend from other artifacts and - for now - gets the job done.
flatten*clj
(flatten* doc-tree)Given a DocTree structure, return all "nodes" with children removed.
Given a DocTree structure, return all "nodes" with children removed.
get-subtreeclj
(get-subtree doc-tree slug-path)Return the node for the given slug-path (including its children). Again, this would probably be way simpler with Zippers :)
Return the node for the given slug-path (including its children). Again, this would probably be way simpler with Zippers :)
process-tocclj
(process-toc slurp-fn toc)Process a doctree toc and inline all file contents via slurp-fn.
The toc should be a collection of ::hiccup-entrys.
The return value will be a ::doctree. Individual nodes will have
an :attrs key with additional metadata such as the original file
name, the file contents and a slug derived from the entry title.
Process a doctree `toc` and inline all file contents via `slurp-fn`. The `toc` should be a collection of `::hiccup-entry`s. The return value will be a `::doctree`. Individual nodes will have an `:attrs` key with additional metadata such as the original file name, the file contents and a slug derived from the entry title.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close