feat: 🎸 Generate docs pages list programatically

The docs pages list are generated based on the contents of the docs/src folder. ✅ Closes: #32
abelsiqueira · May 15, 2024 · 868a111 · 868a111
1 parent 027d819
commit 868a111
Show file tree

Hide file tree

Showing 13 changed files with 49 additions and 29 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning].
 ### Changed
 
 - Update Cirrus CI image_family (#31)
+- Prefix some doc files with a number and generate the pages programatically (#32)
 
 ### Fixed
 

diff --git a/README.md b/README.md
@@ -118,10 +118,10 @@ This structure should be self-informative, as it is part of what most people use
 - PackageName.jl/
   - docs/
     - src/
-      - contributing.md
-      - developer.md
+      - 90-contributing.md
+      - 90-developer.md
       - index.md
-      - reference.md
+      - 90-reference.md
     - make.jl
     - Project.toml
   - src/
@@ -136,8 +136,8 @@ This structure should be self-informative, as it is part of what most people use
 The exceptions are:
 
 - `test/Project.toml`: This is supported for a while, and it looks better. Time will tell if it was a bad idea.
-- `docs/src/contributing.md`: Also known as CONTRIBUTING.md, it explains how contributors can get involved in the project.
-- `docs/src/developer.md`: Also known as README.dev.md, it explains how to setup your local environment.
+- `docs/src/90-contributing.md`: Also known as CONTRIBUTING.md, it explains how contributors can get involved in the project.
+- `docs/src/90-developer.md`: Also known as README.dev.md, it explains how to setup your local environment.
 
 ### Linting and Formatting
 

diff --git a/copier.yml b/copier.yml
@@ -77,8 +77,8 @@ _skip_if_exists:
   - "**/*.jl"
   - "!docs/make.jl"
   - "**/*.md"
-  - "!docs/src/contributing.md"
-  - "!docs/src/developer.md"
+  - "!docs/src/90-contributing.md"
+  - "!docs/src/90-developer.md"
   - "**/Project.toml"
   - CITATION.cff
   - LICENSE

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,10 +1,7 @@
-# Don't forget to run
-#
-#     pkg> dev ..
-#
 [deps]
-Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 COPIERTemplate = "5022dd56-1d41-4538-9f4c-b20739ff8283"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 
 [compat]
 Documenter = "1"
diff --git a/docs/make.jl b/docs/make.jl
@@ -3,6 +3,16 @@ using Documenter
 
 DocMeta.setdocmeta!(COPIERTemplate, :DocTestSetup, :(using COPIERTemplate); recursive = true)
 
+const page_rename = Dict("developer.md" => "Dev setup")
+
+function nice_name(file)
+  file = replace(file, r"^[0-9]*-" => "")
+  if haskey(page_rename, file)
+    return page_rename[file]
+  end
+  return splitext(file)[1] |> x -> replace(x, "-" => " ") |> titlecase
+end
+
 makedocs(;
   modules = [COPIERTemplate],
   doctest = true,
@@ -16,10 +26,11 @@ makedocs(;
     assets = ["assets/style.css"],
   ),
   pages = [
-    "Home" => "index.md",
-    "Contributing" => "contributing.md",
-    "Dev setup" => "developer.md",
-    "Reference" => "reference.md",
+    "Home" => "index.md"
+    [
+      nice_name(file) => file for
+      file in readdir(joinpath(@__DIR__, "src")) if file != "index.md" && splitext(file)[2] == ".md"
+    ]
   ],
 )
 

diff --git a/docs/src/contributing.md → docs/src/90-contributing.md b/docs/src/contributing.md → docs/src/90-contributing.md
@@ -22,5 +22,5 @@ Otherwise, say what your proposed solution is and wait for a discussion around i
 >
 > Feel free to ping us after a few days if there are no responses.
 
-If your solution involves code (or something that requires running the package locally), check the [developer documentation](developer.md).
+If your solution involves code (or something that requires running the package locally), check the [developer documentation](90-developer.md).
 Otherwise, you can use the GitHub interface directly to create your pull request.
diff --git a/docs/src/developer.md → docs/src/90-developer.md b/docs/src/developer.md → docs/src/90-developer.md
@@ -1,6 +1,6 @@
 # Developer documentation
 
-If you haven't, please read the [Contributing guidelines](contributing.md) first.
+If you haven't, please read the [Contributing guidelines](90-contributing.md) first.
 
 ## Linting and formatting
 

diff --git a/docs/src/reference.md → docs/src/90-reference.md b/docs/src/reference.md → docs/src/90-reference.md
@@ -3,13 +3,13 @@
 ## Contents
 
 ```@contents
-Pages = ["reference.md"]
+Pages = ["90-reference.md"]
 ```
 
 ## Index
 
 ```@index
-Pages = ["reference.md"]
+Pages = ["90-reference.md"]
 ```
 
 ```@autodocs

diff --git a/template/README.md.jinja b/template/README.md.jinja
@@ -19,7 +19,7 @@ If you use {{ PackageName }}.jl in your work, please cite using the reference gi
 
 ## Contributing
 
-If you want to make contributions of any kind, please first that a look into our [contributing guide directly on GitHub](docs/src/contributing.md) or the [contributing page on the website](https://{{ PackageOwner }}.github.io/{{ PackageName }}.jl/dev/contributing/).
+If you want to make contributions of any kind, please first that a look into our [contributing guide directly on GitHub](docs/src/90-contributing.md) or the [contributing page on the website](https://{{ PackageOwner }}.github.io/{{ PackageName }}.jl/dev/contributing/).
 
 ---
 

diff --git a/template/docs/make.jl.jinja b/template/docs/make.jl.jinja
@@ -3,6 +3,16 @@ using Documenter
 
 DocMeta.setdocmeta!({{ PackageName }}, :DocTestSetup, :(using {{ PackageName }}); recursive = true)
 
+const page_rename = Dict("developer.md" => "Developer docs") # Without the numbers
+
+function nice_name(file)
+  file = replace(file, r"^[0-9]*-" => "")
+  if haskey(page_rename, file)
+    return page_rename[file]
+  end
+  return splitext(file)[1] |> x -> replace(x, "-" => " ") |> titlecase
+end
+
 makedocs(;
   modules = [{{ PackageName }}],
   doctest = true,
@@ -16,10 +26,11 @@ makedocs(;
     assets = ["assets/style.css"],
   ),
   pages = [
-    "Home" => "index.md",
-    "Contributing" => "contributing.md",
-    "Dev setup" => "developer.md",
-    "Reference" => "reference.md",
+    "Home" => "index.md";
+    [
+      nice_name(file) => file for
+      file in readdir(joinpath(@__DIR__), "src") if file != "index.md" && splitext(file[2]) == ".md"
+    ]
   ],
 )
 

diff --git a/template/docs/src/contributing.md.jinja → template/docs/src/90-contributing.md.jinja b/template/docs/src/contributing.md.jinja → template/docs/src/90-contributing.md.jinja
@@ -22,5 +22,5 @@ Otherwise, say what your proposed solution is and wait for a discussion around i
 >
 > Feel free to ping us after a few days if there are no responses.
 
-If your solution involves code (or something that requires running the package locally), check the [developer documentation](developer.md).
+If your solution involves code (or something that requires running the package locally), check the [developer documentation](90-developer.md).
 Otherwise, you can use the GitHub interface directly to create your pull request.
diff --git a/template/docs/src/developer.md.jinja → template/docs/src/90-developer.md.jinja b/template/docs/src/developer.md.jinja → template/docs/src/90-developer.md.jinja
@@ -1,6 +1,6 @@
 # Developer documentation
 
-If you haven't, please read the [Contributing guidelines](contributing.md) first.
+If you haven't, please read the [Contributing guidelines](90-contributing.md) first.
 
 ## Linting and formatting
 

diff --git a/template/docs/src/reference.md.jinja → template/docs/src/90-reference.md.jinja b/template/docs/src/reference.md.jinja → template/docs/src/90-reference.md.jinja
@@ -3,13 +3,13 @@
 ## Contents
 
 ```@contents
-Pages = ["reference.md"]
+Pages = ["90-reference.md"]
 ```
 
 ## Index
 
 ```@index
-Pages = ["reference.md"]
+Pages = ["90-reference.md"]
 ```
 
 ```@autodocs