From 868a111bbd37567a3ac1ee070f5f3260453bcc11 Mon Sep 17 00:00:00 2001 From: Abel Soares Siqueira Date: Wed, 15 May 2024 15:27:45 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20=F0=9F=8E=B8=20Generate=20docs=20pages?= =?UTF-8?q?=20list=20programatically?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs pages list are generated based on the contents of the docs/src folder. ✅ Closes: #32 --- CHANGELOG.md | 1 + README.md | 10 +++++----- copier.yml | 4 ++-- docs/Project.toml | 7 ++----- docs/make.jl | 19 +++++++++++++++---- .../{contributing.md => 90-contributing.md} | 2 +- docs/src/{developer.md => 90-developer.md} | 2 +- docs/src/{reference.md => 90-reference.md} | 4 ++-- template/README.md.jinja | 2 +- template/docs/make.jl.jinja | 19 +++++++++++++++---- ...ting.md.jinja => 90-contributing.md.jinja} | 2 +- ...veloper.md.jinja => 90-developer.md.jinja} | 2 +- ...ference.md.jinja => 90-reference.md.jinja} | 4 ++-- 13 files changed, 49 insertions(+), 29 deletions(-) rename docs/src/{contributing.md => 90-contributing.md} (92%) rename docs/src/{developer.md => 90-developer.md} (97%) rename docs/src/{reference.md => 90-reference.md} (66%) rename template/docs/src/{contributing.md.jinja => 90-contributing.md.jinja} (93%) rename template/docs/src/{developer.md.jinja => 90-developer.md.jinja} (97%) rename template/docs/src/{reference.md.jinja => 90-reference.md.jinja} (67%) diff --git a/CHANGELOG.md b/CHANGELOG.md index a785915b..f983f708 100644 --- 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 index 44711c07..35115772 100644 --- 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 index ff527e70..3f626e1a 100644 --- 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 index 341f1ed5..23a13cf5 100644 --- 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 index 4eef3614..68d93989 100644 --- 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 b/docs/src/90-contributing.md similarity index 92% rename from docs/src/contributing.md rename to docs/src/90-contributing.md index 45b992e8..34906a91 100644 --- a/docs/src/contributing.md +++ b/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 b/docs/src/90-developer.md similarity index 97% rename from docs/src/developer.md rename to docs/src/90-developer.md index 37f9d2a9..a0f743ba 100644 --- a/docs/src/developer.md +++ b/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 b/docs/src/90-reference.md similarity index 66% rename from docs/src/reference.md rename to docs/src/90-reference.md index 3a86a678..c8d59cb4 100644 --- a/docs/src/reference.md +++ b/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 index 5242bf39..b53d3af7 100644 --- 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 index f127e4fe..246c9e56 100644 --- 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 b/template/docs/src/90-contributing.md.jinja similarity index 93% rename from template/docs/src/contributing.md.jinja rename to template/docs/src/90-contributing.md.jinja index d13a08e5..feaf88e4 100644 --- a/template/docs/src/contributing.md.jinja +++ b/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 b/template/docs/src/90-developer.md.jinja similarity index 97% rename from template/docs/src/developer.md.jinja rename to template/docs/src/90-developer.md.jinja index 43f61613..d774dbc3 100644 --- a/template/docs/src/developer.md.jinja +++ b/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 b/template/docs/src/90-reference.md.jinja similarity index 67% rename from template/docs/src/reference.md.jinja rename to template/docs/src/90-reference.md.jinja index 77e35da3..8dd533f4 100644 --- a/template/docs/src/reference.md.jinja +++ b/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