Skip to content

Commit eb004dd

Browse files
committed
Apply requested changes to scaladoc documentation
1 parent a427977 commit eb004dd

File tree

4 files changed

+40
-35
lines changed

4 files changed

+40
-35
lines changed

docs/docs/usage/scaladoc/changing-versions.md

Lines changed: 0 additions & 29 deletions
This file was deleted.

docs/docs/usage/scaladoc/settings.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,16 +120,17 @@ A directory containing static files from which to generate documentation. Defaul
120120

121121
##### -versions-dictionary-url
122122

123-
A URL pointing to a JSON document containing a dictionary version -> documentation location.
124-
The JSON file has single property "versions" that holds dictionary of labels of specific docs and URL pointing to their index.html top-level file.
125-
Useful for libraries that maintain different releases docs.
123+
A URL pointing to a JSON document containing a dictionary: `version label -> documentation location`.
124+
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
125+
Useful for libraries that maintain different versions of their documentation.
126126

127127
Example JSON file:
128128
```
129129
{
130130
"versions": {
131-
"3.0.X": "https://dotty.epfl.ch/3.0.X/docs/index.html",
131+
"3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
132132
"Nightly": "https://dotty.epfl.ch/docs/index.html"
133133
}
134134
}
135135
```
136+
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Site versioning
3+
---
4+
5+
# {{ page.title }}
6+
7+
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.
8+
9+
### How to setup it
10+
11+
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
12+
13+
Example JSON file:
14+
```
15+
{
16+
"versions": {
17+
"3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
18+
"Nightly": "https://dotty.epfl.ch/docs/index.html"
19+
}
20+
}
21+
```
22+
23+
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.
24+
25+
The important thing to note is that there is only one JSON file to avoid redundancy and each scaladoc must set up it's URL location beforehand, for example:
26+
`doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json")`
27+
28+
29+
### How does it look from user perspective
30+
31+
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.
32+
33+
![](../../../images/scaladoc/nightly.gif)

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,9 +96,9 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
9696
val versionsDictionaryUrl: Setting[String] = StringSetting(
9797
"-versions-dictionary-url",
9898
"versions dictionary url",
99-
"A URL pointing to a JSON document containing a dictionary version -> documentation location. " +
99+
"A URL pointing to a JSON document containing a dictionary `version label -> documentation location`. " +
100100
"The JSON file has single property \"versions\" that holds dictionary of labels of specific docs and URL pointing to their index.html top-level file. " +
101-
"Useful for libraries that maintain different releases docs.",
101+
"Useful for libraries that maintain different versions of their documentation.",
102102
""
103103
)
104104

0 commit comments

Comments
 (0)