dundalek / dinodoc

Polyglot documentation system for building unified documentation sites

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:

• Clojure (source)
  • single project (Promesa) with curated doc pages and API docs
  • compare with codox and cljdoc
• TypeScript (source)
  • including documentation for projects written in other languages within a single site
  • for example TypeScript using docusaurus-plugin-typedoc
• Java using Dokka (source)
  • using Dokka engine
• Java using Javadoc (source)
  • linking to Javadoc-generated pages
• Kotlin (source)
  • using Dokka engine
• Rust (source)
  • based on Rustdoc
• HTTP API (docs)
  • render documentation using OpenAPI spec
  • extract and render API spec from code when using Reitit routes

Architecture:

• Structurizr (docs)
  • architecture documentation with diagrams based on the C4 model
• ContextMapper (source)
  • using Domain Driven Design (DDD) to map Bounded Contexts
• Glossary of terms (source)
  • use Contextive definition format to maintain Ubiquitous Language

Diagrams:

• DB Schema (docs)
  • document tables and visualize schema of relational databases
• Statecharts (docs)
  • state machines and statecharts extracted from source rendered as 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

• Guide describes options and configuration in more detail.
• API Reference

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

• Dinodoc started as a fork of quickdoc and leverages clj-kondo for code analysis.
• Inspired by prior work done by codox and cljdoc.