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

Author: vorburger

.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") {