lein-midje-doc

lein-midje-doc fixes the problem of incorrectly documented examples by bridging the gap between writing tests and writing documentation.

DEPRECATION NOTICE

lein-midje-doc has been DEPRECATED, the new repo can be found at helpshift/hydrox. The announcement was made here.

Whats New

0.0.24

New submodules for working with project

• markdown for testing code in your markdown files
• scaffold for generating test scaffolding from souces
• import for importing docstrings from tests
• purge for removing docstrings from sources

Installation

lein-midje-doc is a leiningen plugin. Install by adding entries in ~/.lein/profiles.clj:

 {:user {:plugins ...
         [lein-midje-doc "0.0.24"]
         ...}}

Notice:

It has come to my attention that users of this plugin will need to install pygments as the library won't work otherwise. This will be definitely be fixed in future versions but I'm a little bit busy right now so please excuse the mess =)

Visit the main site for more information.

Here is a video of the demonstration of a workflow using midje, midje-doc and live-reload. For those that wish to cut to the chase, skip to ~around 7:20

Features:

1. To generate .html documentation from a .clj test file.
2. To express documentation elements as clojure datastructures.
3. To render clojure code and midje facts as code examples.
4. To allow tagging of elements for numbering and linking.

Benefits:

1. All documentation errors can be eliminated.
2. Removes the need to cut and copy test examples into a readme file.
3. Entire test suites can potentially be turned into nice looking documentation with relatively little work.

Turn off Advert Notice

It is hoped that users of lein-midje-doc can leave the Generated By: MidjeDoc notice in order to support this library. It can be turned off by placing {:documentation {:advertise false ...}} in project.clj.

Wishlist for the Future:

In the current state, this library is really just a hack job generating some pretty output. It is hoped that when I find some time, the library can be designed to accommodate more features:

• Latex Features
  • Table of Figures
  • Table of Examples
  • Citations
  • Customisation Numbering
  • Appendices
  • Equations
• Themes
• Elements
  • :reference element for tabulization of ns-publics in a namespace
• Attributes
  • :ignore
• Linking to Multiple Documents (Generate an entire Site)
• Additional Test Suites
  • core.test
  • purnam.test
• pdf output with page numbering
• markdown output
• Codebase
  • Refactor with multimethods
  • Clean up hacked-in code

Contributors

• Chris Zheng
• Yannick Scherer
• Alex Walker

License

Copyright © 2014 Chris Zheng

Distributed under the The MIT License.