Giter VIP home page Giter VIP logo

cljdoc's Introduction

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

For Library Authors | Contributing | Website | ClojuTRE Talk

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

CircleCI

Rationale

๐Ÿ“น I (Martin) gave a talk at ClojuTRE about cljdoc which is probably a good intro if you want to understand what cljdoc is and why it exists. If you prefer text, read on for the 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.

Contributing

To start the entire system, simply run:

./script/cljdoc 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, you can start a REPL with clj, then load the system and move into its namespace:

(require '[cljdoc.server.system])
(in-ns 'cljdoc.server.system)

Now check the comment block at the end of cljdoc.server.system.

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

ADRs

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

License

EPL-2.0 see LICENSE

cljdoc's People

Contributors

alex-dixon avatar angusiguess avatar avichalp avatar bbatsov avatar dawranliou avatar greg-kargin avatar iamdrowsy avatar ikitommi avatar jorinvo avatar jsimpson-ovo avatar karls avatar kkinnear avatar martinklepsch avatar mk avatar nikolap avatar pesterhazy avatar plexus avatar roman01la avatar saskali avatar severeoverfl0w avatar tavistock avatar timothypratley avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.