diff --git a/_config.yml b/_config.yml index 64f78bc718..fa2723f7df 100644 --- a/_config.yml +++ b/_config.yml @@ -125,6 +125,15 @@ defaults: overview-name: "Macros in Scala 3" layout: multipage-overview permalink: "/scala3/guides/macros/:title.html" + - + scope: + path: "_overviews/scala3-scaladoc" + values: + scala3: true + partof: scala3-scaladoc + overview-name: "Scaladoc" + layout: multipage-overview + permalink: "/scala3/guides/scaladoc/:title.html" - scope: path: "_scala3-reference" diff --git a/_overviews/scala3-scaladoc/blog.md b/_overviews/scala3-scaladoc/blog.md new file mode 100644 index 0000000000..1e3c371c8e --- /dev/null +++ b/_overviews/scala3-scaladoc/blog.md @@ -0,0 +1,42 @@ +--- +layout: multipage-overview +title: Built-in blog +partof: scala3-scaladoc +num: 5 +previous-page: static-site +next-page: site-versioning +--- + +Scaladoc allows you to include a simple blog in your documentation. For now, it +provides only basic features. In the future, we plan to include more advanced +features like tagging or author pages. + +Blog is treated a little differently than regular static sites. This article will help you set up your own blog. + +## Proper directory setup + +All your blogposts must be put under `blog/_posts` directory. + + +``` +├── blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +``` + +If you are using yaml [sidebar]({% link _overviews/scala3-scaladoc/static-site.md %}#sidebar) don't forget to place + +``` +sidebar: + - title: Blog +``` + +somewhere inside the `yaml` tree representing the sidebar sections. Scaladoc will attach under that section all of your blogposts. + +## Naming convention + +All the blogpost filenames should start with date in numeric format matching `YYYY-MM-DD`. +Example name is `2015-10-23-dotty-compiler-bootstraps.md`. + + diff --git a/_overviews/scala3-scaladoc/docstrings.md b/_overviews/scala3-scaladoc/docstrings.md new file mode 100644 index 0000000000..5efb8b5f38 --- /dev/null +++ b/_overviews/scala3-scaladoc/docstrings.md @@ -0,0 +1,198 @@ +--- +layout: multipage-overview +title: Docstrings - specific Tags and Features +partof: scala3-scaladoc +num: 2 +previous-page: index +next-page: linking +--- + +This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc. +Since many things are the same as in the old scaladoc, some parts are reused from this [article](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html) + + +Scaladoc extends Markdown with additional features, such as linking +to API definitions. This can be used from within static documentation and blog +posts to provide blend-in content. + + +## Where to put docstrings + +Scaladoc comments go before the items they pertain to in a special comment block that starts with a /** and ends with a */, like this: + +```scala +/** Start the comment here + * and use the left star followed by a + * white space on every line. + * + * Even on empty paragraph-break lines. + * + * Note that the * on each line is aligned + * with the second * in /** so that the + * left margin is on the same column on the + * first line and on subsequent ones. + * + * Close the comment with *\/ + * + * If you use Scaladoc tags (@param, @group, etc.), + * remember to put them at separate lines with nothing preceding. + * + * For example: + * + * Calculate the square of the given number + * + * @param d the Double to square + * @return the result of squaring d + */ + def square(d: Double): Double = d * d +``` + +In the example above, this Scaladoc comment is associated with the method square since it is right before it in the source code. + +Scaladoc comments can go before fields, methods, classes, traits, objects. +For now, scaladoc doesn't support straightforward solution to document packages. There is a dedicated github +[issue](https://github.com/lampepfl/dotty/issues/11284), where you can check the current status of the problem. + +For class primary constructors which in Scala coincide with the definition of the class itself, a @constructor tag is used to target a comment to be put on the primary constructor documentation rather than the class overview. + +## Tags + +Scaladoc uses `@` tags to provide specific detail fields in the comments. These include: + +### Class specific tags + +- `@constructor` placed in the class comment will describe the primary constructor. + +### Method specific tags + +- `@return` detail the return value from a method (one per method). + +### Method, Constructor and/or Class tags + +- `@throws` what exceptions (if any) the method or constructor may throw. +- `@param` detail a value parameter for a method or constructor, provide one per parameter to the method/constructor. +- `@tparam` detail a type parameter for a method, constructor or class. Provide one per type parameter. + +### Usage tags + +- `@see` reference other sources of information like external document links or related entities in the documentation. +- `@note` add a note for pre or post conditions, or any other notable restrictions or expectations. +- `@example` for providing example code or related example documentation. + + +### Member grouping tags + +These tags are well-suited to larger types or packages, with many members. They allow you to organize the Scaladoc page into distinct sections, with each one shown separately, in the order that you choose. + +These tags are not enabled by default! You must pass the -groups flag to Scaladoc in order to turn them on. Typically the sbt for this will look something like: + +```scala +Compile / doc / scalacOptions ++= Seq( + "-groups" +) +``` +Each section should have a single-word identifier that is used in all of these tags, shown as `group` below. By default, that identifier is shown as the title of that documentation section, but you can use @groupname to provide a longer title. + +Typically, you should put @groupprio (and optionally @groupname and @groupdesc) in the Scaladoc for the package/trait/class/object itself, describing what all the groups are, and their order. Then put @group in the Scaladoc for each member, saying which group it is in. + +Members that do not have a `@group` tag will be listed as “Ungrouped” in the resulting documentation. + +- `@group ` - mark the entity as a member of the `` group. +- `@groupname ` - provide an optional name for the group. `` is displayed as the group header before the group description. +- `@groupdesc ` - add optional descriptive text to display under the group name. Supports multiline formatted text. +- `@groupprio ` - control the order of the group on the page. Defaults to 0. Ungrouped elements have an implicit priority of 1000. Use a value between 0 and 999 to set a relative position to other groups. Low values will appear before high values. + +### Other tags + +- `@author` provide author information for the following entity +- `@version` the version of the system or API that this entity is a part of. +- `@since` like `@version` but defines the system or API that this entity was first defined in. +- `@deprecated` marks the entity as deprecated, providing both the replacement implementation that should be used and the version/date at which this entity was deprecated. +- `@syntax ` let you change the parser for docstring. The default syntax is markdown, however you can change it using this directive. Currently available syntaxes are `markdown` or `wiki`, e. g. `@syntax wiki` + +### Macros + +- `@define ` allows use of $name in other Scaladoc comments within the same source file which will be expanded to the contents of ``. + +If a comment is not provided for an entity at the current inheritance level, but is supplied for the overridden entity at a higher level in the inheritance hierarchy, the comment from the super-class will be used. + +Likewise if `@param`, `@tparam`, `@return` and other entity tags are omitted but available from a superclass, those comments will be used. + +### Explicit + +For explicit comment inheritance, use the @inheritdoc tag. + +### Markup + +Scaladoc provides two syntax parsers: `markdown` (default) or `wikidoc`. +It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead. + +#### Markdown + +Markdown uses [commonmark flavour](https://spec.commonmark.org/current/) with two custom extensions: +- `wikidoc` links for referencing convenience +- `wikidoc` codeblocks with curly braces syntax + + +#### Wikidoc + +Wikidoc is syntax used for scala2 scaladoc. It is supported because of many existing source code, however it is **not** recommended to use it in new projects. +Wikisyntax can be toggled on with flag `-comment-syntax wiki` globally, or with `@syntax wiki` directive in docstring. + +Some of the standard markup available: + +``` +`monospace` +''italic text'' +'''bold text''' +__underline__ +^superscript^ +,,subscript,, +[[entity link]], e.g. [[scala.collection.Seq]] +[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]] +``` + +For more info about wiki links look at this [chapter](#linking-to-api) + +Other formatting notes + +- Paragraphs are started with one (or more) blank lines. `*` in the margin for the comment is valid (and should be included) but the line should be blank otherwise. +- Headings are defined with surrounding `=` characters, with more `=` denoting subheadings. E.g. `=Heading=`, `==Sub-Heading==`, etc. +- List blocks are a sequence of list items with the same style and level, with no interruptions from other block styles. Unordered lists can be bulleted using `-`, numbered lists can be denoted using `1.`, `i.`, `I.`, or `a.` for the various numbering styles. In both cases, you must have extra space in front, and more space makes a sub-level. + +The markup for list blocks looks like: + +``` +/** Here is an unordered list: + * + * - First item + * - Second item + * - Sub-item to the second + * - Another sub-item + * - Third item + * + * Here is an ordered list: + * + * 1. First numbered item + * 1. Second numbered item + * i. Sub-item to the second + * i. Another sub-item + * 1. Third item + */ +``` + +### General Notes for Writing Scaladoc Comments + +Concise is nice! Get to the point quickly, people have limited time to spend on your documentation, use it wisely. +Omit unnecessary words. Prefer returns X rather than this method returns X, and does X,Y & Z rather than this method does X, Y and Z. +DRY - don’t repeat yourself. Resist duplicating the method description in the @return tag and other forms of repetitive commenting. + +More details on writing Scaladoc + +Further information on the formatting and style recommendations can be found in Scala-lang scaladoc style guide. + +## Linking to API + +Scaladoc allows linking to API documentation with Wiki-style links. Linking to +`scala.collection.immutable.List` is as simple as +`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation]({% link _overviews/scala3-scaladoc/linking.md %}#definition-links). diff --git a/_overviews/scala3-scaladoc/index.md b/_overviews/scala3-scaladoc/index.md new file mode 100644 index 0000000000..b158e9d89e --- /dev/null +++ b/_overviews/scala3-scaladoc/index.md @@ -0,0 +1,11 @@ +--- +layout: multipage-overview +title: Scaladoc +partof: scala3-scaladoc +num: 1 +next-page: docstrings +--- + +![scaladoc logo]({{ site.baseurl }}/resources/images/scala3/scaladoc/logo.svg) + +scaladoc is a tool to generate the API documentation of your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`. diff --git a/_overviews/scala3-scaladoc/linking.md b/_overviews/scala3-scaladoc/linking.md new file mode 100644 index 0000000000..635c461abd --- /dev/null +++ b/_overviews/scala3-scaladoc/linking.md @@ -0,0 +1,99 @@ +--- +layout: multipage-overview +title: Linking documentation +partof: scala3-scaladoc +num: 3 +previous-page: docstrings +next-page: static-site +--- + +Scaladoc's main feature is creating API documentation from code comments. + +By default, the code comments are understood as Markdown, though we also support +Scaladoc's old [Wiki syntax](https://docs.scala-lang.org/style/scaladoc.html). + +## Syntax + +### Definition links + +Our definition link syntax is quite close to Scaladoc's syntax, though we have made some +quality-of-life improvements. + +#### Basic syntax + +A definition link looks as follows: `[[scala.collection.immutable.List]]`. + +Which is to say, a definition link is a sequence of identifiers separated by +`.`. The identifiers can be separated with `#` as well for Scaladoc compatibility. + +By default, an identifier `id` references the first (in source order) entity +named `id`. An identifier can end with `$`, which forces it to refer to a value +(an object, a value, a given); an identifier can also end with `!`, which forces +it to refer to a type (a class, a type alias, a type member). + +The links are resolved relative to the current location in source. That is, when +documenting a class, the links are relative to the entity enclosing the class (a +package, a class, an object); the same applies to documenting definitions. + +Special characters in links can be backslash-escaped, which makes them part of +identifiers instead. For example, `` [[scala.collection.immutable\.List]] `` +references the class named `` `immutable.List` `` in package `scala.collection`. + +#### New syntax + +We have extended Scaladoc definition links to make them a bit more pleasant to +write and read in source. The aim was also to bring the link and Scala syntax +closer together. The new features are: + +1. `package` can be used as a prefix to reference the enclosing package + Example: + ``` + package utils + class C { + def foo = "foo". + } + /** See also [[package.C]]. */ + class D { + def bar = "bar". + } + ``` + The `package` keyword helps make links to the enclosing package shorter + and a bit more resistant to name refactorings. +1. `this` can be used as a prefix to reference the enclosing classlike + Example: + ``` + class C { + def foo = "foo" + /** This is not [[this.foo]], this is bar. */ + def bar = "bar" + } + ``` + Using a Scala keyword here helps make the links more familiar, as well as + helps the links survive class name changes. +1. Backticks can be used to escape identifiers + Example: + ``` + def `([.abusive.])` = ??? + /** TODO: Figure out what [[`([.abusive.])`]] is. */ + def foo = `([.abusive.])` + ``` + Previously (versions 2.x), Scaladoc required backslash-escaping to reference such identifiers. Now (3.x versions), + Scaladoc allows using the familiar Scala backtick quotation. + +#### Why keep the Wiki syntax for links? + +There are a few reasons why we've kept the Wiki syntax for documentation links +instead of reusing the Markdown syntax. Those are: + +1. Nameless links in Markdown are ugly: `[](definition)` vs `[[definition]]` + By far, most links in documentation are nameless. It should be obvious how to + write them. +2. Local member lookup collides with URL fragments: `[](#field)` vs `[[#field]]` +3. Overload resolution collides with MD syntax: `[](meth(Int))` vs `[[meth(Int)]]` +4. Now that we have a parser for the link syntax, we can allow spaces inside (in + Scaladoc one needed to slash-escape those), but that doesn't get recognized + as a link in Markdown: `[](meth(Int, Float))` vs `[[meth(Int, Float)]]` + +None of these make it completely impossible to use the standard Markdown link +syntax, but they make it much more awkward and ugly than it needs to be. On top +of that, Markdown link syntax doesn't even save any characters. diff --git a/_overviews/scala3-scaladoc/settings.md b/_overviews/scala3-scaladoc/settings.md new file mode 100644 index 0000000000..88272e80ab --- /dev/null +++ b/_overviews/scala3-scaladoc/settings.md @@ -0,0 +1,138 @@ +--- +layout: multipage-overview +title: Settings +partof: scala3-scaladoc +num: 7 +previous-page: site-versioning +--- + +This chapter lists the configuration options that can be used when calling scaladoc. Some of the information shown here can be found by calling scaladoc with the `-help` flag. + +## Parity with scaladoc for Scala 2 + +Scaladoc has been rewritten from scratch and some of the features turned out to be useless in the new context. +If you want to know what is current state of compatibility with scaladoc old flags, you can visit this issue for tracking [progress](https://github.com/lampepfl/dotty/issues/11907). + +## Providing settings + +Supply scaladoc settings as command-line arguments, e.g., `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. If called from sbt, +update the value of `Compile / doc / scalacOptions`, e. g. `Compile / doc / scalacOptions ++= Seq("-d", "output", "-project", "my-project")` + +## Overview of all available settings + +##### -project +The name of the project. To provide compatibility with Scala2 aliases with `-doc-title` + +##### -project-version +The current version of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-version` + +##### -project-logo +The logo of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-logo` + +##### -project-footer +The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer` + +##### -comment-syntax +The styling language used for parsing comments. +Currently we support two syntaxes: `markdown` or `wiki` +If setting is not present, scaladoc defaults `markdown` + +##### -revision +Revision (branch or ref) used to build project project. Useful with sourcelinks to prevent them from pointing always to the newest master that is subject to changes. + +##### -source-links +Source links provide a mapping between file in documentation and code repository. + +Example source links is: +`-source-links:docs=github://lampepfl/dotty/master#docs` + +Accepted formats: + +\=\ +\ + +where \ is one of following: + - `github:///[/revision][#subpath]` + will match https://github.com/$organization/$repository/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber] + when revision is not provided then requires revision to be specified as argument for scaladoc + - `gitlab:///` + will match https://gitlab.com/$organization/$repository/-/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber] + when revision is not provided then requires revision to be specified as argument for scaladoc + - \ + +\ is a format for `doc-source-url` parameter from old scaladoc. +NOTE: We only supports `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, + €{FILE_PATH}, and €{FILE_LINE} patterns. + + +Template can defined only by subset of sources defined by path prefix represented by ``. +In such case paths used in templates will be relativized against `` + + + +##### -external-mappings + +Mapping between regexes matching classpath entries and external documentation. + +Example external mapping is: +`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/` + +A mapping is of the form '\::\[scaladoc3|scaladoc|javadoc]::\'. You can supply several mappings, separated by commas, as shown in the example. + +##### -social-links + +Links to social sites. For example: + +`-social-links:github::https://github.com/lampepfl/dotty,gitter::https://gitter.im/scala/scala,twitter::https://twitter.com/scala_lang` + +Valid values are of the form: '\[github|twitter|gitter|discord]::link'. Scaladoc also supports 'custom::link::white_icon_name::black_icon_name'. In this case icons must be present in 'images/' directory. + +##### -skip-by-id + +Identifiers of packages or top-level classes to skip when generating documentation. + +##### -skip-by-regex + +Regexes that match fully qualified names of packages or top-level classes to skip when generating documentation. + +##### -doc-root-content + +The file from which the root package documentation should be imported. + +##### -author + +Adding authors in docstring with `@author Name Surname` by default won't be included in generated html documentation. +If you would like to label classes with authors explicitly, run scaladoc with this flag. + +##### -groups + +Group similar functions together (based on the @group annotation) + +##### -private + +Show all types and members. Unless specified, show only public and protected types and members. + +##### -doc-canonical-base-url + +A base URL to use as prefix and add `canonical` URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated. + +##### -siteroot + +A directory containing static files from which to generate documentation. Default directory is `./docs` + +##### -versions-dictionary-url + +A URL pointing to a JSON document containing a dictionary: `version label -> documentation location`. +The JSON file has single property `versions` that holds the dictionary associating the labels of specific versions of the documentation to the URLs pointing to their index.html +Useful for libraries that maintain different versions of their documentation. + +Example JSON file: +``` +{ + "versions": { + "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", + "Nightly": "https://dotty.epfl.ch/docs/index.html" + } +} +``` + diff --git a/_overviews/scala3-scaladoc/site-versioning.md b/_overviews/scala3-scaladoc/site-versioning.md new file mode 100644 index 0000000000..e48907d11e --- /dev/null +++ b/_overviews/scala3-scaladoc/site-versioning.md @@ -0,0 +1,39 @@ +--- +layout: multipage-overview +title: Site versioning +partof: scala3-scaladoc +num: 6 +previous-page: blog +next-page: settings +--- + +Scaladoc provides a convenient way to switch between different versions of the documentation. The feature is useful if we want to expose older docs for users that didn't migrate to the new version of our library. + +### How to setup it + +The feature was designed for easy scalability with no need to regenerate all scaladocs after adding a new version. To do so a new setting is introduced: `-versions-dictionary-url`. Its argument must be a URL to a JSON document holding information about the locations of specific versions. The JSON file has single property `versions` that holds the dictionary associating the labels of specific versions of the documentation to the URLs pointing to their index.html + +Example JSON file: +``` +{ + "versions": { + "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", + "Nightly": "https://dotty.epfl.ch/docs/index.html" + } +} +``` + +This enforce us to provide the setting while generating docs for each of the versions, however it gives us more flexibility later. If you want to add a version of the API docs next to the previous 5 versions that you have already published, then you only need to upload the new docs to a web server and add a new entry to the JSON file. All versions of the site will now become aware of the new site version. + +The important thing to note is that there is only one JSON file to avoid redundancy and each scaladoc must set up its URL location beforehand, for example, in sbt: + +``` +doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json") +``` + + +### How does it look from user perspective + +Providing a JSON file via `-versions-dictionary-url` enables scaladoc to link between versions. It is also convenient to be able to change the revision label in the drop-down menu. Everything will change automatically. + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/nightly.gif) diff --git a/_overviews/scala3-scaladoc/static-site.md b/_overviews/scala3-scaladoc/static-site.md new file mode 100644 index 0000000000..36a3bc11d2 --- /dev/null +++ b/_overviews/scala3-scaladoc/static-site.md @@ -0,0 +1,158 @@ +--- +layout: multipage-overview +title: Static documentation +partof: scala3-scaladoc +num: 4 +previous-page: linking +next-page: blog +--- + +Scaladoc is able to generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/). +Having a combined tool allows to provide interaction between static documentation and API, thus allowing the two to blend naturally. + +Creating a site is just as simple as in Jekyll. The site root contains the +layout of the site and all files placed there 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 files in generated documentation: + +``` +index.html +docs/getting-started.html +``` + +Scaladoc can transform both files and directories (to organize your documentation into tree-like structure). By default directories has title based on file name and has empty content. There is an option to include `index.html` or `index.md` (not both) to provide both content and properties like title (see [Properties](#properties)). + +## Properties + +Scaladoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine +and provides a number of custom filters and tags specific to Scala +documentation. + +In Scaladoc, all templates can contain YAML front-matter. The front-matter +is parsed and put into the `page` variable available in templates via Liquid. + +Scaladoc uses some predefined properties to controls some aspect of page. + +Predefined properties: + + - **title** provide page title that will be used in navigation and html metadata. + - **extraCss** additional `.css` files that will be included in this page. Paths should be relative to documentation root. **This setting is not exported to template engine.** + - **extraJs** additional `.js` files that will be included in this page. Paths should be relative to documentation root. **This setting is not exported to template engine.** + - **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs etc.) but only token html wrapper to provide metadata and resources (js and css files). **This setting is not exported to template engine.** +- **layout** - predefined layout to use, see below. **This setting is not exported to template engine.** + + +## Using existing Templates and Layouts + +To perform template expansion, Dottydoc looks at the `layout` field 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 +``` + +## Sidebar + +Scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root: + +```yaml +sidebar: + - title: Blog + - 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 however it accepts both files and directories and latter can be used to provide deeper structures. + +The items must provide either `subsection` or `url` but not both at once! +The only exception is `Blog` which is only a `title` and behaves differently. +You can read more about blog [here]({% link _overviews/scala3-scaladoc/blog.md %}). + +``` +├── blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +├── index.html +└── sidebar.yml +``` + +## Static resources + +You can attach static resources (pdf, images) to your documentation by using two dedicated directories: +`resources` and `images`. When you upload your assests under any of these directories you can reference them in markdown +as if they were relatively at the same level. + +For example, consider the following situation: + +``` +├── blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +├── index.html +├── resources +│ └── my_file.pdf +├── images +│ └── my_image.png +└── sidebar.yml + +``` + +You can refer to the assets from within any of the files using markdown links: + +``` +This is my blogpost. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf) +``` diff --git a/_sass/layout/type-md.scss b/_sass/layout/type-md.scss index ccaed1bb9e..0696bee09f 100755 --- a/_sass/layout/type-md.scss +++ b/_sass/layout/type-md.scss @@ -45,8 +45,7 @@ h5 { font-size: 1.0rem; font-family: $base-font-family; - text-transform: uppercase; - font-weight: $font-regular; + font-weight: $font-bold; } } diff --git a/resources/images/scala3/scaladoc/logo.svg b/resources/images/scala3/scaladoc/logo.svg new file mode 100644 index 0000000000..1774519639 --- /dev/null +++ b/resources/images/scala3/scaladoc/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/resources/images/scala3/scaladoc/nightly.gif b/resources/images/scala3/scaladoc/nightly.gif new file mode 100644 index 0000000000..d6e764a032 Binary files /dev/null and b/resources/images/scala3/scaladoc/nightly.gif differ diff --git a/scala3/guides.md b/scala3/guides.md index 45587d280f..028858ab27 100644 --- a/scala3/guides.md +++ b/scala3/guides.md @@ -18,6 +18,11 @@ guides: icon: birthday-cake url: "/scala3/guides/tasty-overview.html" description: "An overview over the TASTy format aimed at end-users of the Scala language." + - title: Scaladoc + by: Krzysztof Romanowski, Aleksander Boruch-Gruszecki, Andrzej Ratajczak + icon: book + url: "/scala3/guides/scaladoc" + description: "Scala’s API documentation generation tool." ---