:memo: 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:
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, usev0.7.1
.
To run Literator from sbt, use generateDocs
task.
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.
If you use sbt-release plugin, you can add docs generation step. See sbt-release documentation for details.
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.
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.
Yes, you're very welcome to contribute to the project. Check open issues with the help wanted
badge.
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 are a couple of interesting projects which approach literate programming in Scala from another side:
tut
sheds