1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
---
layout: doc-page
title: Dottydoc
---
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](http://jekyllrb.com/)
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:
```none
├── docs
│ └── getting-started.md
└── index.html
```
This will give you a site with the following endpoints:
```none
_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](https://shopify.github.io/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`:
```html
---
layout: main
---
<h1>Hello world!</h1>
```
With a simple main template like this:
{% raw %}
```html
<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.
{% endraw %}
Layouts must be placed in a `_layouts` directory in the site root:
```none
├── _layouts
│ └── main.html
├── docs
│ └── getting-started.md
└── index.html
```
It is also possible to use one of the [default layouts](#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:
```none
├── 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:
```html
<div class="container">
{% raw %}{% include "sidebar.html" %}{% endraw %}
</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](#default-includes), but the user-specified
includes may override these.
An example structure with an include file "sidebar.html":
```none
├── _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:
```yaml
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:
```none
├── 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:
```markdown
[Seq](scala.collection.immutable.Seq)
```
Linking to members is done in the same fashion:
```markdown
[Seq](scala.collection.immutable.Seq.isEmpty)
```
Dottydoc denotes objects by ending their names in "$". To select `Object.range`
you'd therefore write:
```markdown
[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:
```html
{% raw %}{% docstring "scala.collection.immutable.Seq" %}{% endraw %}
```
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](https://github.com/lampepfl/dotty/issues/new)!
Default Layouts
===============
main.html
---------
A wrapper for all other layouts, includes a default `<head>` with included
JavaScripts and CSS style-sheets.
### Variables ###
* `content`: placed in `<body>` tag
* `extraCSS`: a list of relative paths to extra CSS style-sheets for the site
* `extraJS`: a list of relative paths to extra JavaScripts for the site
* `title`: the `<title>` of the page
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 ###
* `content`: placed in a `<div>` with class `content-body`
* `docs`: the API docs generated from supplied source files, this is included by
default and does not need to be specified.
doc-page.html
-------------
Doc page is used for pages that need a sidebar and provides a small wrapper for
the included {% raw %}`{{ content}}`{% endraw %}.
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
================
* `scala-logo.svg`: the scala in dotty version as svg
* `toc.html`: the default table of contents template
|
