Dottydoc

Edit this page on GitHub

Dottydoc is a tool to generate a combined documentation and API reference for your project.

In previous versions of the Scaladoc tool, there is a big divide between what is documentation and what is API reference. Dottydoc allows referencing, citing and rendering parts of your API in your documentation, thus allowing the two to blend naturally.

To do this, Dottydoc is very similar to what Jekyll provides in form of static site generation. As you probably guessed, this whole site was created using Dottydoc.

Creating a site is just as simple as in Jekyll. The site root contains the layout of the site and all files placed here will be either considered static, or processed for template expansion.

The files that are considered for template expansion must end in *.{html,md} and will from here on be referred to as "template files" or "templates".

A simple "hello world" site could look something like this:

├── docs
│   └── getting-started.md
└── index.html

This will give you a site with the following endpoints:

_site/index.html
_site/docs/getting-started.html

Just as with Jekyll, the site is rendered in a _site directory.

Using existing Templates and Layouts

Dottydoc uses the Liquid templating engine and provides a number of custom filters and tags specific to Scala documentation.

In Dottydoc, all templates can contain YAML front-matter. The front-matter is parsed and put into the page variable available in templates via Liquid.

To perform template expansion, Dottydoc looks at layout in the front-matter. Here's a simple example of the templating system in action, index.html:

---
layout: main
---

<h1>Hello world!</h1>

With a simple main template like this:

<html>
    <head>
        <title>Hello, world!</title>
    </head>
    <body>
        {{ content }}
    </body>
</html>

Would result in {{ content }} being replaced by <h1>Hello world!</h1> from the index.html file.

Layouts must be placed in a _layouts directory in the site root:

├── _layouts
│   └── main.html
├── docs
│   └── getting-started.md
└── index.html

It is also possible to use one of the default layouts that ship with Dottydoc.

Blog

Dottydoc also allows for a simple blogging platform in the same vein as Jekyll. Blog posts are placed within the ./blog/_posts directory and have to be on the form year-month-day-title.{md,html}.

An example of this would be:

├── blog
│   └── _posts
│       └── 2016-12-05-implicit-function-types.md
└── index.html

To be rendered as templates, each blog post should have front-matter and a layout declaration.

The posts are also available in the variable site.posts throughout the site. The fields of these objects are the same as in [BlogPost](dotty.tools.dottydoc.staticsite.BlogPost).

Includes

In Liquid, there is a concept of include tags, these are used in templates to include other de facto templates:

<div class="container">
    {% include "sidebar.html" %}
</div>

You can leave out the file extension if your include ends in .html.

Includes need to be kept in _includes in the site root. Dottydoc provides a couple of default includes, but the user-specified includes may override these.

An example structure with an include file "sidebar.html":

├── _includes
│   └── sidebar.html
├── blog
│   ├── _posts
│   │   └── 2016-12-05-implicit-function-types.md
│   └── index.md
└── index.html

Sidebar

Dottydoc gives you the ability to create your own custom table of contents, this can either be achieved by overriding the toc.html include - or by providing a sidebar.yml file in the site root:

sidebar:
    - title: Blog
      url: blog/index.html
    - title: Docs
      url: docs/index.html
    - title: Usage
      subsection:
        - title: Dottydoc
          url: docs/usage/dottydoc.html
        - title: sbt-projects
          url: docs/usage/sbt-projects.html

The sidebar key is mandatory, as well as title for each element. The default table of contents allows you to have subsections - albeit the current depth limit is 2 - we'd love to see this change, contributions welcome!

The items which have the subsection key, may not have a url key in the current scheme. A site root example with this could be:

├── blog
│   └── _posts
│       └── 2016-12-05-implicit-function-types.md
├── index.html
└── sidebar.yml

Dottydoc Specific Tags and Behavior

Linking to API

If you for instance, want to link to scala.collection.immutable.Seq in a markdown file, you can simply use the canonical path in your url:

[Seq](scala.collection.immutable.Seq)

Linking to members is done in the same fashion:

[Seq](scala.collection.immutable.Seq.isEmpty)

Dottydoc denotes objects by ending their names in "$". To select Object.range you'd therefore write:

[Object.range](scala.collection.immutable.List$.range)

Rendering Docstrings

Sometimes you end up duplicating the docstring text in your documentation, therefore Dottydoc makes it easy to render this inline:

{% docstring "scala.collection.immutable.Seq" %}

Other extensions

We would love to have your feedback on what you think would be good in order to render the documentation you want! Perhaps you'd like to render method definitions or members? Let us know by filing issues!

Default Layouts

main.html

A wrapper for all other layouts, includes a default <head> with included JavaScripts and CSS style-sheets.

Variables

sidebar.html

Sidebar uses main.html as its parent layout. It adds a sidebar generated from a YAML file (if exists), as well as the index for the project API.

Variables

doc-page.html

Doc page is used for pages that need a sidebar and provides a small wrapper for the included {{ content}}.

api-page.html

The last two layouts are special, in that they are treated specially by Dottydoc. The input to the API page is a documented [Entity](dotty.tools.dottydoc.model.Entity). As such, this page can be changed to alter the way Dottydoc renders API documentation.

blog-page.html

A blog page uses files placed in ./blog/_posts/ as input to render a blog.

Default Includes