Literator

Generate literate-style markdown docs from your sources

Literator produces a readable document from your code, i.e to helps you to use literate programming when it's not supported by the language itself.

You can write your code using markdown syntax in block comments and then transform it to a markdown document. Then you can generate a nice html or pdf or whatever else, using your favorite markdown processor (for example Pandoc).

Literator is written in Scala and first of all for Scala, but it should work for some other languages as well. Open an issue, if you want support for something else.

Some extra features:

• generates a list of link definitions for references between files
• generates a tree-index of the files and (optionally) appends it to each produced markdown file

Usage

Just add following line to your project/plugins.sbt:

addSbtPlugin("laughedelic" % "literator" % "<version>")

(see the latest release version on the badge above)

Note that since v0.8.0 this plugin is published only for sbt-1.x. If you need it for sbt-0.13, use v0.7.1.

To run Literator from sbt, use generateDocs task.

Setting keys

Key	Type	Default
docsMap	Map[File, File]	src/ → docs/src/
docsOutputDirs	Seq[File]	same as docsMap values
docsAddIndex	Boolean	false
docsCleanBefore	Boolean	true

You can set docsMap key in your build.sbt to map source directories to output documentation directories. Using this map you can easily generate docs for several subprojects or integrate certain parts of the source documentation in the general docs (especially if you're using some service like Read the Docs).

Note that output directories are cleaned up before generating docs (you can turn it off with docsCleanBefore := false), so be careful if you're mixing generated docs with handwritten.

Release process integration

If you use sbt-release plugin, you can add docs generation step. See sbt-release documentation for details.

Example

If you have a piece of code like this (it's from the literator sources):

/* ### Block comments parsing */

/* - When parsing the comment opening brace, we remember the offset for the content
     Note that [scaladoc-style comments](http://docs.scala-lang.org/style/scaladoc.html)
     are ignored.
*/
def commentStart: PS =
  spaces ~ (lang.comment.start ^^ { _.replaceAll(".", " ") }) ~
  (((spaces ~ guard(eol)) ^^^ None) | // if the first row is empty, ignore it
   (guard(not("*")) ~> " ".?)) ^^     // not scaladoc and an optional space
  { case sps ~ strt ~ sp => sps + strt + sp.getOrElse("") }

/* - Closing comment brace is just ignored */
def commentEnd: PS = spaces ~ lang.comment.end ^^^ ""

Then it will be transformed into the following markdown:

### Block comments parsing

- When parsing the comment opening brace, we remember the offset for the content
  Note that [scaladoc-style comments](http://docs.scala-lang.org/style/scaladoc.html)
  are ignored.

```scala
def commentStart: PS =
  spaces ~ (lang.comment.start ^^ { _.replaceAll(".", " ") }) ~
  (((spaces ~ guard(eol)) ^^^ None) | // if the first row is empty, ignore it
   (guard(not("*")) ~> " ".?)) ^^     // not scaladoc and an optional space
  { case sps ~ strt ~ sp => sps + strt + sp.getOrElse("") }
```

- Closing comment brace is just ignored

```scala
def commentEnd: PS = spaces ~ lang.comment.end ^^^ ""
```

---

You can see the result of running Literator on its own sources in the docs/src/ folder.

FAQ

Is this project alive?

Yes, even if you don't see any recent commits/releases. It's just quite stable. In @ohnosequences we used this tool in everyday development and as a part of the release process.

Can I help with development?

Yes, you're very welcome to contribute to the project. Check open issues with the help wanted badge.

Why not docco?

Of course, there are plenty of docco-like tools, which generate htmls from your sources (also using markdown), but there are several reasons, why I don't like them:

• there is no normal Scala-clone of such tool that you could integrate in the release process
• most of such tools support only one-line comments and ignore block comments, while the opposite makes more sense: write documentation comments as normal text and keep small technical comments inlined
• those tools claim to be "quick and dirty", IMO better to have something simple, but reliable
• Literator helps to keep things simple using markdown which is good as an intermediate format. For example, it's handy to have just markdown documents on github, as it will render them nicely and then generate from them htmls for a web-site if needed using your favorite tool and style templates

Related projects

There are a couple of interesting projects which approach literate programming in Scala from another side:

• tut reads markdown files and interprets Scala code in tut sheds
• sbt-scaliterate generates Scala source code from a programming book written in markdown