Socco

Socco is a Scala compiler plugin to generate documentation from Scala source files.

It produces HTML documents that display your comments alongside your code. Comments are passed through Markdown, and the Scala code is syntax highlighted, typed and linked to the appropriate API Doc.

Examples

Here are a few examples generated by Socco. The source .scala files can be found in examples/src/main/scala.

1. Statefully transforming streams with fs2.
2. Parsing JSON with circe. Using a custom stylesheet.
3. Scala collections tour. Abusing the model to produce a more classical documentation 🙀.

Usage

If you use SBT, add the following settings to enable the plugin:

autoCompilerPlugins := true
addCompilerPlugin("com.criteo.socco" %% "socco-plugin" % "0.1.6")

If you are using scalac directly, add the following option:

-Xplugin:com.criteo.socco.socco-plugin_2.12-0.1.6.jar

This can be followed by any of the available options:

• -P:out:$outDir to specify the output directory.
• -P:style:$stylesheetPath to specify a custom stylesheet.
• -P:packagge_$packageName:$scalaDocUrl to specify a Scala API doc to link.
• -P:header:$headerPath to specify a custom HTML header.
• -P:footer:$footerPath to specify a custom HTML footer.

Syntax

The plugin will handle all scala source files starting with a comment line like:

// Example: (.*)

The captured group will be used as the example title in the generated HTML documents.

The comments can use markdown syntax, and will be correctly rendered to the generated documentation.

Also, there is a special kind of comment:

// @className

When added on top of a code block, it will add the CSS class to the generated block. Allowing you to style it further wit CSS.

Prior art

• Docco generates this kind of layout for coffeescript code. It has been ported to several other languages.
• Tut is a documentation tool that allow to embed (and compile) scala code into Markdown documents. Which is exactly the opposite of Socco 😛.
• SXR is Scala compiler plugin that turn source code into syntax highlighted and browsable HTML documents. It is outdated now but was a good source of inspiration for socco.

License

This project is licensed under the Apache 2.0 license.

Copyright

Copyright © Criteo, 2017.