ci/doc: 更新 HTML 构建，添加缺失的 md 文件 (#142)

* doc: 更新构建脚本 - 去除了 Transifex 编辑链接的修改 * doc: base\multi-threading 移除重复的部分 * doc: manual\unicode-input 使用新版的生成代码以兼容 Documenter v1.8.0+ * doc: 修复内部链接 * doc: remove EditURL * doc: 放松 html 大小警告 * doc: 暂时不提供 source url * ci: 区分 html/pdf 构建分组 * doc: 开启 pr 构建预览 * doc: 指定 repolink * doc: 修复外部的标准库 source url * doc: 修复大部分文档的 md 源文件映射 * doc.stdlib: 删除 EditURL * doc.stdlib: 添加缺失的标准库文档 * doc.build: 修复 stdlib 函数 source 链接 * doc.build: 使用清理自定义 Remote 实现 * doc: 清理 todo * doc.build: 修复 gitlab CI 的错误 * ci: 使用 julia v1.10 进行构建 * ci: 更正文件夹名
JuliaCN · Dec 21, 2024 · 2f13d82 · 2f13d82
1 parent a6fa9d7
commit 2f13d82
Show file tree

Hide file tree

Showing 33 changed files with 360 additions and 322 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -10,7 +10,7 @@ on:
 concurrency:
   # Skip intermediate builds: always.
   # Cancel intermediate builds: only if it is a pull request build.
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.ref }}-html
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 
 jobs:
@@ -28,7 +28,7 @@ jobs:
           show-versioninfo: true
       - uses: julia-actions/cache@v2
       - name: Install dependencies
-        shell: julia --project=docs --color=yes {0}
+        shell: julia --project=doc --color=yes {0}
         run: |
           using Pkg
           Pkg.develop(PackageSpec(path=pwd()))

diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml
@@ -10,7 +10,7 @@ on:
 concurrency:
   # Skip intermediate builds: always.
   # Cancel intermediate builds: only if it is a pull request build.
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.ref }}-pdf
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 
 jobs:

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -1,4 +1,6 @@
-image: julia:1
+# DOC: https://gitlab.cn/docs/jh/ci/docker/using_docker_images.html
+# 保持和 doc/Project.toml 中的版本一致
+image: julia:1.10
 
 before_script:
   - julia --version
@@ -11,7 +13,6 @@ before_script:
 pages:
   stage: deploy
   script:
-    - cp -r zh_CN/* ./
     - julia --project=doc --check-bounds=yes --color=yes -e 'include("doc/make.jl")'
     - mv doc/build public
   artifacts:

diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "JuliaZH"
 uuid = "652e05fd-ed22-5b6c-bf99-44e63a676e5f"
-version = "1.6.0"
+version = "1.10.0"
 
 [deps]
 PkgServerClient = "9c9e696b-6b05-402c-8ae4-5dc38852c714"

diff --git a/contrib/HTMLWriter.jl b/contrib/HTMLWriter.jl
@@ -1,16 +1,7 @@
 # override Documenter.jl/src/Writers/HTMLWriter.jl
 using Dates
-import Documenter: Documents, Documenter, Writers, Utilities
-import Documenter.Utilities.DOM: DOM, Tag, @tags
+import Documenter.DOM: @tags
 import Documenter.Writers.HTMLWriter:
-    getpage,
-    render_head,
-    render_article,
-    open_output,
-    mdconvert,
-    pagetitle,
-    navhref,
-    domify,
     render_settings,
     THEMES
 
@@ -27,125 +18,50 @@ const zh_CN_days = [
 Dates.LOCALES["zh_CN"] = Dates.DateLocale(zh_CN_months, zh_CN_months_abbrev, zh_CN_days, [""])
 
 #=
-  1. 修改编辑翻译提示语
-    - 改 icon 为 FontAwesome: fa-globe(f0ac)
-    - 改 "Edit on Github" 为 “完善 Transifex 上的翻译"
-    - 改为对应的 Transifex URL
-  2. 修改前后翻页提示语
-    - "Previous" => t_Previous
-    - "Next" => t_Next
+  1. （右上角）设置弹窗提示语
 =#
 
-const t_Edit_on_xx = " 完善 Transifex 上的翻译" # 开头加空格，避免与 icon 靠太近
-const t_Icon = "\uf0ac" # fa-globe
+"""
+Renders the modal settings dialog.
+渲染（右上角）设置弹窗。
 
-# 生成对应文件在 Transifex 上的翻译地址
-function transifex_url(rel_path)
-    # 首页源文件在 GitHub 上
-    if splitdir(rel_path) == splitdir("src/index.md")
-        return "https://github.com/JuliaCN/JuliaZH.jl/blob/master/doc/src/index.md"
-    end
-
-    # rel_path => "src\\manual\\getting-started.md"
-
-    paths, file_name = splitdir(rel_path)
-    # paths     => "src\\manual"
-    # file_name => "getting-started.md"
-
-    _, parent_fold = splitdir(paths)
-    # parent_fold => "manual"
-
-    page_name = replace(file_name, '.' => "")
-    # page_name => "getting-startedmd"
-
-    # final URL =>
-    #   "https://www.transifex.com/juliacn/manual-zh_cn/translate/#zh_CN/getting-startedmd"
-    "https://www.transifex.com/juliacn/$parent_fold-zh_cn/translate/#zh_CN/$page_name"
-end
-
-
-
-# workaround on Documenter/#977
-function Documenter.Writers.HTMLWriter.render_navbar(ctx, navnode, edit_page_link::Bool)
-    @tags div header nav ul li a span
-
-    # The breadcrumb (navigation links on top)
-    navpath = Documents.navpath(navnode)
-    header_links = map(navpath) do nn
-        title = mdconvert(pagetitle(ctx, nn); droplinks=true)
-        nn.page === nothing ? li(a[".is-disabled"](title)) : li(a[:href => navhref(ctx, nn, navnode)](title))
-    end
-    header_links[end] = header_links[end][".is-active"]
-    breadcrumb = nav[".breadcrumb"](
-        ul[".is-hidden-mobile"](header_links),
-        ul[".is-hidden-tablet"](header_links[end]) # when on mobile, we only show the page title, basically
-    )
-
-    # The "Edit on GitHub" links and the hamburger to open the sidebar (on mobile) float right
-    navbar_right = div[".docs-right"]
-
-    # Set the logo and name for the "Edit on.." button.
-    if edit_page_link && (ctx.settings.edit_link !== nothing) && !ctx.settings.disable_git
-        host_type = Utilities.repo_host_from_url(ctx.doc.user.repo)
-        logo = t_Icon
-
-        pageurl = get(getpage(ctx, navnode).globals.meta, :EditURL, getpage(ctx, navnode).source)
-        edit_branch = isa(ctx.settings.edit_link, String) ? ctx.settings.edit_link : nothing
-
-        # 1.3: 改 URL
-        url = transifex_url(getpage(ctx, navnode).source)
-        if url !== nothing
-            title = t_Edit_on_xx
-            push!(navbar_right.nodes,
-                a[".docs-edit-link", :href => url, :title => title](
-                    span[".docs-icon.fab"](logo),
-                    span[".docs-label.is-hidden-touch"](title)
-                )
-            )
-        end
-    end
-
-    # Settings cog
-    push!(navbar_right.nodes, a[
-        "#documenter-settings-button.docs-settings-button.fas.fa-cog",
-        :href => "#", :title => "设置",
-    ])
-
-    # Hamburger on mobile
-    push!(navbar_right.nodes, a[
-        "#documenter-sidebar-button.docs-sidebar-button.fa.fa-bars.is-hidden-desktop",
-        :href => "#"
-    ])
-
-    # Construct the main <header> node that should be the first element in div.docs-main
-    header[".docs-navbar"](breadcrumb, navbar_right)
-end
-
-function render_settings(ctx)
+修改之处标记为 XXX
+https://github.com/JuliaDocs/Documenter.jl/blob/v1.8.0/src/html/HTMLWriter.jl#L913
+"""
+function render_settings()
     @tags div header section footer p button hr span select option label a
 
     theme_selector = p(
-        label[".label"]("选择主题"),
+        label[".label"]("选择主题"),  # XXX
         div[".select"](
-            select["#documenter-themepicker"](option[:value=>theme](theme) for theme in THEMES)
+            select["#documenter-themepicker"](
+                option[:value => "auto"]("Automatic (OS)"),
+                (option[:value => theme](theme) for theme in THEMES)...,
+            )
         )
     )
 
+    # XXX: 使用本地时间格式
     now_full = Dates.format(now(), "Y U d E HH:MM"; locale="zh_CN")
     now_short = Dates.format(now(), "Y U d E"; locale="zh_CN")
+    # XXX: 修改构建信息格式
+    # EN    : This document was generated with Documenter.jl version 1.8.0 on Tuesday 12 November 2024. Using Julia version 1.11.1.
+    # zh_CN : 本文档在 2024 年 11 月 12 日星期二用 Documenter.jl 1.8.0 版生成。 使用 1.11.1 版本的 Julia。
     buildinfo = p(
-        "本文档在",
+        "本文档在 ",
         span[".colophon-date", :title => now_full](now_short),
-        "由",
+        "用 ",
         a[:href => "https://github.com/JuliaDocs/Documenter.jl"]("Documenter.jl"),
-        "使用$(Base.VERSION)版本的Julia生成。"
+        " $(Documenter.DOCUMENTER_VERSION)",
+        " 版生成",
+        "使用 $(Base.VERSION) 版本的 Julia。"
     )
 
-    div["#documenter-settings.modal"](
+    return div["#documenter-settings.modal"](
         div[".modal-background"],
         div[".modal-card"](
             header[".modal-card-head"](
-                p[".modal-card-title"]("设置"),
+                p[".modal-card-title"]("设置"), # XXX
                 button[".delete"]()
             ),
             section[".modal-card-body"](

diff --git a/doc/Project.toml b/doc/Project.toml
@@ -1,5 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterInventoryWritingBackport = "195adf08-069f-4855-af3e-8933a2cdae94"
-DocumenterLaTeX = "cd674d7a-5f81-5cf3-af33-235ef1834b99"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[compat]
+Documenter = "1"
+julia = "1.10"