From 866e364dde76aa5df42548bf72d2f5c4d200535b Mon Sep 17 00:00:00 2001 From: Felix Mulder Date: Tue, 24 Jan 2017 17:35:53 +0100 Subject: Document dottydoc capabilities, add anchored headers --- docs/blog/index.html | 2 +- docs/docs/usage/dottydoc.md | 260 ++++++++++++++++++++++++++++++++++++++++++++ docs/sidebar.yml | 2 + 3 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 docs/docs/usage/dottydoc.md (limited to 'docs') 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 +--- + +

Hello world!

+``` + +With a simple main template like this: + +{% raw %} +```html + + + Hello, world! + + + {{ content }} + + +``` + +Would result in `{{ content }}` being replaced by `

Hello world!

` 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 +

+ {% raw %}{% include "sidebar.html" %}{% endraw %} +

+``` + +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 `` with included +JavaScripts and CSS style-sheets. + +### Variables ### +* `content`: placed in `` 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 `` 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 -- cgit v1.2.3