Fix broken Dokka API Doc links on brand new website (#2533)

.gitignore

@@ -90,3 +90,7 @@ lint/tmp/
 # Note: The docs/ directory is our SOURCE (in MD),
 # and the site/ directory is our TARGET (in HTML)
 site/
+# but the Dokka API Doc is generated into docs/
+# (which is slightly confusing, but helps mkdocs to validate links)
+# so we ignore that here, as it's a built artifact that should not be committed
+docs/use/api/*/**

build-docs.bash

@@ -20,15 +20,12 @@ set -euox pipefail
 rm -rf site/
 mkdir -p site/
 
+# We need to generate the Dokka API Doc into docs/use/api/ *before* running mkdocs,
+# so that it can validate the links to it and make sure that they are not broken.
+./gradlew dokkaHtml
+
 # "install --deploy" is better than "sync", because it checks that the Pipfile.lock
 # is up-to-date with the Pipfile before installing. If it's not, it will fail the
 # installation. This is useful for ensuring strict dependency control during CI.
 pipenv install --deploy
-pipenv run mkdocs build
-
-./gradlew dokkaHtml
-mkdir -p site/api/
-mv docs/data-capture site/api/
-mv docs/engine site/api/
-mv docs/knowledge site/api/
-mv docs/workflow site/api/
+pipenv run mkdocs build --strict

datacapture/build.gradle.kts

@@ -123,7 +123,7 @@ dependencies {
 
 tasks.dokkaHtml.configure {
  outputDirectory.set(
- file("../docs/${Releases.DataCapture.artifactId}/${Releases.DataCapture.version}"),
+ file("../docs/use/api/${Releases.DataCapture.artifactId}/${Releases.DataCapture.version}"),
  )
  suppressInheritedMembers.set(true)
  dokkaSourceSets {

docs/use/api.md

@@ -1,6 +1,6 @@
 # API
 
-* [Engine](/api/engine/1.0.0/)
-* [Data Capture](/data-capture/1.1.0/)
-* [Workflow](/api/workflow/0.1.0-alpha04/)
-* [Knowledge](/api/knowledge/0.1.0-alpha03/)
+* [Engine](api/engine/1.0.0/index.html)
+* [Data Capture](api/data-capture/1.1.0/index.html)
+* [Workflow](api/workflow/0.1.0-alpha04/index.html)
+* [Knowledge](api/knowledge/0.1.0-alpha03/index.html)

engine/build.gradle.kts

@@ -158,7 +158,9 @@ dependencies {
 }
 
 tasks.dokkaHtml.configure {
- outputDirectory.set(file("../docs/${Releases.Engine.artifactId}/${Releases.Engine.version}"))
+ outputDirectory.set(
+ file("../docs/use/api/${Releases.Engine.artifactId}/${Releases.Engine.version}"),
+ )
  suppressInheritedMembers.set(true)
  dokkaSourceSets {
  named("main") {

knowledge/build.gradle.kts

@@ -113,7 +113,7 @@ dependencies {
 
 tasks.dokkaHtml.configure {
  outputDirectory.set(
- file("../docs/${Releases.Knowledge.artifactId}/${Releases.Knowledge.version}"),
+ file("../docs/use/api/${Releases.Knowledge.artifactId}/${Releases.Knowledge.version}"),
  )
  suppressInheritedMembers.set(true)
  dokkaSourceSets {

mkdocs.yaml

@@ -5,6 +5,7 @@ edit_uri: blob/master/docs/
 copyright: Copyright 2024 The Android FHIR SDK Authors
 
 nav:
+ - Home: index.md
  - Users:
  - API: use/api.md
  - Contributors:
@@ -36,3 +37,17 @@ plugins:
  - git-revision-date-localized
  - minify:
  minify_html: true
+
+# https://www.mkdocs.org/user-guide/configuration/#validation
+# Nota Bene: There is no "error" level in MkDocs, but the build-docs.bash script
+# uses "mkdocs build --strict", which cause MkDocs to abort the build on any warnings.
+validation:
+ nav:
+ not_found: warn
+ absolute_links: warn
+ omitted_files: warn
+ links:
+ anchors: warn
+ not_found: warn
+ absolute_links: warn
+ unrecognized_links: warn

workflow/build.gradle.kts

@@ -122,7 +122,9 @@ dependencies {
 }
 
 tasks.dokkaHtml.configure {
- outputDirectory.set(file("../docs/${Releases.Workflow.artifactId}/${Releases.Workflow.version}"))
+ outputDirectory.set(
+ file("../docs/use/api/${Releases.Workflow.artifactId}/${Releases.Workflow.version}"),
+ )
  suppressInheritedMembers.set(true)
  dokkaSourceSets {
  named("main") {