diff options
| author | Felix Mulder <felix.mulder@gmail.com> | 2017-01-24 17:35:53 +0100 |
|---|---|---|
| committer | Felix Mulder <felix.mulder@gmail.com> | 2017-01-31 14:35:42 +0100 |
| commit | 866e364dde76aa5df42548bf72d2f5c4d200535b (patch) | |
| tree | a0fe7c27c533e293255471aa6f34b272ef61e9c1 /docs | |
| parent | e59241a2852eab53bdc0e22ea5b2dd394b231913 (diff) | |
| download | dotty-866e364dde76aa5df42548bf72d2f5c4d200535b.tar.gz dotty-866e364dde76aa5df42548bf72d2f5c4d200535b.tar.bz2 dotty-866e364dde76aa5df42548bf72d2f5c4d200535b.zip | |
Document dottydoc capabilities, add anchored headers
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/blog/index.html | 2 | ||||
| -rw-r--r-- | docs/docs/usage/dottydoc.md | 260 | ||||
| -rw-r--r-- | docs/sidebar.yml | 2 |
3 files changed, 263 insertions, 1 deletions
diff --git a/docs/blog/index.html b/docs/blog/index.html index b821a25cc..b4725def7 100644 --- a/docs/blog/index.html +++ b/docs/blog/index.html @@ -1,5 +1,5 @@ --- -layout: blog +layout: blog-page title: "Blog" --- diff --git a/docs/docs/usage/dottydoc.md b/docs/docs/usage/dottydoc.md new file mode 100644 index 000000000..bbfae7081 --- /dev/null +++ b/docs/docs/usage/dottydoc.md @@ -0,0 +1,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: + +``` +├── 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](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: + +``` +├── _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: + +``` +├── 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": + +``` +├── _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: + +``` +├── 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 diff --git a/docs/sidebar.yml b/docs/sidebar.yml index 6353b3c90..7ffa1f5b7 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -9,6 +9,8 @@ sidebar: url: docs/usage/cbt-projects.html - title: sbt-projects url: docs/usage/sbt-projects.html + - title: Dottydoc + url: docs/usage/dottydoc.html - title: Migrating url: docs/usage/migrating.html - title: Contributing |