Skip to content

Polyglot documentation system for building unified documentation sites

License

Notifications You must be signed in to change notification settings

dundalek/dinodoc

Repository files navigation

Dinodoc

Dinodoc is a documentation tool that generates API documentation from source code with linked markdown articles. It aims to enable creating a unified documentation hub within an organization.

Dinodoc is designed to generate documentation from multiple sources. It supports documenting multiple projects in a monorepo or across repos, and projects written in other languages besides Clojure.

Features

It works on top of Docusaurus which provides:

  • Modern look with Light/Dark theme
  • Include API documentation for non-Clojure languages like TypeScript
  • Document HTTP APIs of services with OpenAPI
  • Additional features like Search, Diagrams, Analytics, Blog
  • Large ecosystem of community plugins
  • Complementary tools like CMS intergration to make writing docs easier for non-developers

Examples

API documentation:

Architecture:

Diagrams:

Combining mono and multi repos:

  • Reitit (source)
    • monorepo with multiple modules
    • API docs combined into a single namespace hierarchy
  • Polylith (source)
    • monorepo with components
    • API docs rendered separately for each component
  • Ring (source)
    • mix of monorepo and multiple repos
    • modules in a main monorepo and additional modules in separate repositories
    • API docs rendered separately under each module

Usage

  1. Create a new Docusaurus site:
    npx create-docusaurus@latest my-website classic
  2. Add alias with dependencies to deps.edn:
    {:aliases
     {:doc {:extra-deps {io.github.dundalek/dinodoc {:git/tag "v0.3.0" :git/sha "9d5e861"}
            :main-opts ["doc.clj"]}}}
  3. Create the script to generate docs and save as doc.clj:
    Defaults are to use source files in src/ to generate API docs and doc/ for markdown pages.
    (ns doc
      (:require [dinodoc.api :as dinodoc]))
    
    (dinodoc/generate
     {:inputs ["."]
      :output-path "docs"})
    
    (shutdown-agents)
  4. Generate markdown API docs:
    clojure -M:doc
  5. Render the site:
    npm start to start dev-server in watch mode
    npm run build to build the static site for deployment

Documentation

Status

Alpha, there are issues to iron out and improvements to be made. The main points at this stage are:

  • Figure out the useful feature set.
  • Possibly try out some experimental features with good leverage based on Living Documentation principles.
  • Settle on good defaults that cover most common uses and figure out minimal required configuration options needed for customization.

Credits