wip seo updates for #6

JuliaComputing · Jun 26, 2023 · 306406c · 306406c
1 parent f530d11
commit 306406c
Show file tree

Hide file tree

Showing 10 changed files with 27 additions and 19 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -43,18 +43,26 @@ end
 
 # These lists are reused in the makedocs, but also in the at-contents
 # blocks on the src/index.md page.
-const PAGES_GUIDES = [
-    "guides/authentication.md",
-    "guides/datasets.md",
-    "guides/jobs.md",
+PAGES_GUIDES = [
+    "Authentication" => "guides/authentication.md",
+    "Datasets" => "guides/datasets.md",
+    "Jobs" => "guides/jobs.md",
 ]
-const PAGES_REFERENCE = [
-    "reference/authentication.md",
-    "reference/job-submission.md",
-    "reference/jobs.md",
-    "reference/datasets.md",
+PAGES_REFERENCE = [
+    "Authentication" => "reference/authentication.md",
+    "Job submission" => "reference/job-submission.md",
+    "Jobs" => "reference/jobs.md",
+    "Datasets" => "reference/datasets.md",
     "reference/exceptions.md",
 ]
+# When using PAGES_GUIDES and PAGES_REFERENCE in at-contents blocks, we only
+# want the paths to the markdown files, so we drop the page title bits with
+# this function.
+function droptitles(pages)
+    map(pages) do page
+        isa(page, Pair) ? page[2] : page
+    end
+end
 Mocking.apply(mocking_patch) do
     makedocs(;
         sitename="JuliaHub.jl",

diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
@@ -263,7 +263,7 @@ This tutorial has hopefully given an overview of basic JuliaHub.jl usage.
 For more advanced usage, you may want to read through the more detailed how-to guides.
 
 ```@contents
-Pages = Main.PAGES_GUIDES
+Pages = Main.droptitles(Main.PAGES_GUIDES)
 Depth = 1:1
 ```
 

diff --git a/docs/src/guides/authentication.md b/docs/src/guides/authentication.md
@@ -2,7 +2,7 @@
 CurrentModule=JuliaHub
 ```
 
-# [Authentication](@id guide-authentication)
+# [Authentication guide](@id guide-authentication)
 
 In order to talk to a JuliaHub instance, you must authenticate with your user account, and have an authentication token.
 JuliaHub.jl aims to make it as easy and painless as possible to manage your authentication tokens.

diff --git a/docs/src/guides/datasets.md b/docs/src/guides/datasets.md
@@ -6,7 +6,7 @@ DocTestSetup = :(using JuliaHub)
 using JuliaHub
 ```
 
-# [Datasets](@id guide-datasets)
+# [Datasets guide](@id guide-datasets)
 
 JuliaHub.jl offers a programmatic way to work with your JuliaHub datasets, and this section demonstrates a few common workflows you can use with these APIs.
 

diff --git a/docs/src/guides/jobs.md b/docs/src/guides/jobs.md
@@ -6,7 +6,7 @@ DocTestSetup = :(using JuliaHub)
 using JuliaHub
 ```
 
-# Jobs
+# Jobs guide
 
 JuliaHub.jl can be used to both [submit new jobs](../reference/job-submission.md), and to [inspect running or finished jobs](../reference/jobs.md).
 

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -13,14 +13,14 @@ If you are unfamiliar with JuliaHub.jl, you may want to start out by reading thr
 If you want to know in detail how to programmatically work with a particular JuliaHub feature, you may want to skim through the applicable how-to guide:
 
 ```@contents
-Pages = Main.PAGES_GUIDES
+Pages = Main.droptitles(Main.PAGES_GUIDES)
 Depth = 1:1
 ```
 
 Finally, detailed explanations and API references of JuliaHub.jl features and functions are available in the reference section of the manual:
 
 ```@contents
-Pages = Main.PAGES_REFERENCE
+Pages = Main.droptitles(Main.PAGES_REFERENCE)
 Depth = 1:1
 ```
 

diff --git a/docs/src/reference/authentication.md b/docs/src/reference/authentication.md
@@ -3,7 +3,7 @@ CurrentModule=JuliaHub
 DocTestSetup = :(using JuliaHub)
 ```
 
-# [Authentication](@id authentication)
+# [Authentication API reference](@id authentication)
 
 In order to talk to a JuliaHub instance, you need to have a valid authentication token.
 JuliaHub reuses the Julia's built-in package server authentication tokens for this purpose.

diff --git a/docs/src/reference/datasets.md b/docs/src/reference/datasets.md
@@ -7,7 +7,7 @@ DocTestSetup = :(using JuliaHub)
 using JuliaHub
 ```
 
-# [Datasets](@id datasets)
+# [Datasets API reference](@id datasets)
 
 These APIs allow you to create, read, update, and delete datasets owned by [the currently authenticated user](@ref authentication).
 

diff --git a/docs/src/reference/job-submission.md b/docs/src/reference/job-submission.md
@@ -3,7 +3,7 @@ CurrentModule=JuliaHub
 DocTestSetup = :(using JuliaHub)
 ```
 
-# [Job submission](@id job-submission)
+# [Job submission API reference](@id job-submission)
 
 On JuliaHub you can submit _jobs_, which are user-defined workloads that get allocated a dedicated compute capacity.
 For example, this includes running scripts in batch computations, cloud IDEs, interactive notebooks and so on.

diff --git a/docs/src/reference/jobs.md b/docs/src/reference/jobs.md
@@ -6,7 +6,7 @@ DocTestSetup = :(using JuliaHub)
 using JuliaHub
 ```
 
-# [Jobs](@id job-apis)
+# [Jobs API reference](@id job-apis)
 
 JuliaHub.jl provides various methods to inspect and interact jobs that [have been submitted to JuliaHub](@ref job-submission).
 It is also possible to get access to job outputs programmatically.
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,7 +6,7 @@ DocTestSetup = :(using JuliaHub) @@
     using JuliaHub
     ```
-    # Jobs
+    # Jobs guide
     JuliaHub.jl can be used to both [submit new jobs](../reference/job-submission.md), and to [inspect running or finished jobs](../reference/jobs.md).
@@ Expand Down @@