alex-dixon / cljdoc

A future central documentation hub for the Clojure community πŸ™Œ

Home Page:https://cljdoc.xyz

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

cljdoc is a platform to build, host and view Clojure/Script library documentation

CircleCI

An effort to create a central documentation hub for the Clojure & ClojureScript ecosystem.

πŸ‘‹ Need help getting started? Say hi on Telegram, Twitter or Clojurians Slack in #cljdoc.

Rationale

Publishing Clojure library documentation is an often manual and error prone process. Library authors who want to provide documentation need to set up tooling to create such documentation, host it and keep it updated. In combination all these steps introduce a significant amount of friction that often leads to there not being any HTML documentation at all. If there is documentation it's often only a matter of time until it's out of date with the latest release.

In short: Publishing documentation is hard. Harder than it has to be.

By fully automating the process of publishing documentation we can take a great burden from the shoulders of library maintainers and let them focus on shipping great libraries with great documentation.

A central place and consistent UI for all Clojure/Script library documentation will also make it easier for developers to find and work with documentation.

By centralizing this publishing process we can also build up a global understanding of the Clojure/Script ecosystem enabling many more interesting use-cases down the road.

Goals

  • Provide an easy way to host library documentation for Clojure/Script library authors
  • Deal with all the boring stuff: hosting, updating, keeping old versions around
  • Build an ecosystem-encompassing database (+ API) of artifacts, namespaces and their contents.
  • Support API documentation, articles and examples.
  • Encourage the writing of more and better documentation.

Design

  • an ecosystem-encompassing Grimoire store serves as single source of truth
  • that Grimoire store is updated when new releases are published to Clojars or other relevant information changes
  • various tools can be built on top of data in this Grimoire store
    • it acts as a repository for static analysis done on Clojure code

ADRs

I've been looking for an opportunity to use ADRs for some time, you can find them all in doc/adr/.

Contributing

To start the entire system, simply run:

boot run

After that the server will start under http://localhost:8000/. You can navigate to a projects documentation page like http://localhost:8000/d/bidi/bidi/2.1.3/ and request a build. This will analyze Bidi's source code locally and store the result. After that is done you can reload the page and view the documentation.

Logs can be viewed with tail -f log/cljdoc.log.

♻️ For a more REPL-driven workflow, check the comment block at the end of the cljdoc.server.system namespace.

Tests: There is a small amount of tests which can be ran with boot test.

License

EPL-2.0 see LICENSE

About

A future central documentation hub for the Clojure community πŸ™Œ

https://cljdoc.xyz

License:Eclipse Public License 2.0


Languages

Language:Clojure 87.5%Language:Shell 5.4%Language:HCL 4.5%Language:CSS 1.4%Language:JavaScript 0.8%Language:HTML 0.3%Language:Makefile 0.1%