covering Modern Julia Workflows

Author: Rratic

README.md

@@ -35,7 +35,7 @@ julia> DoctreePages.generate("./zh", "./zh-output");
 
 ## TODO
 文档覆盖
-- [ ] [Modern Julia Workflows](https://modernjuliaworkflows.org/)
+- [x] [Modern Julia Workflows](https://modernjuliaworkflows.org/)
 - [x] Julia DataScience
 - [x] [Road2Coding](https://github.com/rd2coding/Road2Coding)
 - [ ] [noob-data-analysis](https://github.com/noob-data-analaysis/data-analysis)

docs/basic/dev_skills.md

@@ -63,6 +63,9 @@ julia> @warn "This is bad" a + b
 
 可以更进一步使用 [ProgressLogging.jl](https://github.com/JuliaLogging/ProgressLogging.jl) 提供的 `@progress` 去显示进度条，使用 [Suppressor.jl](https://github.com/JuliaIO/Suppressor.jl) 抑制一些消息。
 
+!!! info
+	`@debug` 消息默认被抑制。可通过设置环境变量 `JULIA_DEBUG` 为模块名（通常为 `Main` 或你的包模块名）来启用它们。
+
 ## 热更新
 可以使用 [Revise.jl](https://github.com/timholy/Revise.jl) 在运行时热更新一些代码。
 
@@ -75,7 +78,30 @@ catch e
 end
 ```
 
+## 启动文件
+Julia 每次启动时会自动执行位于 `.julia/config/startup.jl` 的**启动文件**。大多数 Julia 开发者会在此文件中加载一些常用的开发工具。[^1]
+
+除了[热更新](#热更新)中提到的 Revise.jl，还可以加载影响 REPL 体验的包：
+
+* [OhMyREPL.jl](https://github.com/KristofferC/OhMyREPL.jl)：为 REPL 提供语法高亮，被广泛使用
+* [AbbreviatedStackTraces.jl](https://github.com/BioTurboNick/AbbreviatedStackTraces.jl)：缩短错误堆栈跟踪，避免信息过多淹没关键内容
+* [Term.jl](https://github.com/FedeClaudi/Term.jl)：提供更美观的类型和错误显示方式
+
+[StartupCustomizer.jl](https://github.com/abraemer/StartupCustomizer.jl) 可帮助配置和管理启动文件。
+
 ## 调试
-[Infiltrator.jl](https://github.com/JuliaDebug/Infiltrator.jl) 允许你给自己的代码加入断点。
+[Infiltrator.jl](https://github.com/JuliaDebug/Infiltrator.jl) 允许你给自己的代码加入断点。调用命中断点的函数后，REPL 提示符会变为 `infil>`，输入 `?` 可查看可用命令。
+
+`@exfiltrate` 宏可以将局部变量转移到全局存储 `safehouse` 中，便于断点外继续分析：[^1]
+```julia-repl
+infil> @exfiltrate k F   # 将 k、F 存入 safehouse
+infil> @continue
+
+julia> safehouse.k       # 在普通模式下访问
+```
+
+[Debugger.jl](https://github.com/JuliaDebug/Debugger.jl) 的功能更强：它甚至允许你给别人的代码加入断点。使用 `@enter` 宏进入函数调用，提示符变为 `1|debug>`，可使用导航命令单步执行，按反引号切换到 `` 1|julia> `` 模式后可在当前上下文中求值任意表达式。
+
+VSCode 提供了[图形化调试界面](https://www.julia-vscode.org/docs/stable/userguide/debugging/)：点击行号左侧设置断点（显示为红色圆点），在 Julia 扩展的调试面板中点击 `Run and Debug` 启动调试器。程序在断点处暂停后，可通过顶部工具栏继续、单步跳过、单步进入或跳出。[^1]
 
-[Debugger.jl](https://github.com/JuliaDebug/Debugger.jl) 的功能更强：它甚至允许你给别人的代码加入断点。
+[^1]: [Modern Julia Workflows - Writing your code](https://modernjuliaworkflows.org/writing/)

docs/workflow/develop.md

@@ -26,11 +26,20 @@
 
 如果还需初始化 Git，可使用 `git init` 命令。
 
+### PkgTemplates.jl
+[PkgTemplates.jl](https://github.com/JuliaCI/PkgTemplates.jl) 可以自动化完成创建包时的常见配置，生成比 `generate` 更丰富的项目框架（包含 `.gitignore`、`LICENSE`、GitHub Actions 工作流等）。[^2]
+
+```julia-repl
+julia> using PkgTemplates
+julia> t = Template(user="myuser", interactive=false)
+julia> t("MyAwesomePackage")
+```
+
+之后将生成的目录推送到 GitHub 仓库即可。[PackageMaker.jl](https://github.com/Eben60/PackageMaker.jl) 提供了 PkgTemplates.jl 的图形化封装，操作更加便捷。
+
 也可以参照：
 - [官方提供的包示例](https://github.com/JuliaLang/Example.jl)
-- [包模板生成器](https://invenia.github.io/PkgTemplates.jl/stable/)
-
-获得更丰富的模板。
+- [包模板生成器文档](https://juliaci.github.io/PkgTemplates.jl/stable/)
 
 ## 包的配置
 包的配置数据写在 `Project.toml` 文件中。这个文件使用 [TOML 格式](../knowledge/toml.md)
@@ -104,6 +113,73 @@ Base.Math
 
 [FAQ](https://github.com/JuliaRegistries/General#faq)
 
+## GitHub Actions 与 CI
+[PkgTemplates.jl](https://github.com/JuliaCI/PkgTemplates.jl) 会在 `.github/workflows/` 目录下自动生成 [GitHub Actions](https://docs.github.com/en/actions/quickstart) 工作流文件（YAML 格式）。其中 `CI.yml` 会在每次 pull request、tag 或推送到 `main` 分支时自动运行测试。对于公开仓库，GitHub 提供免费的无限工作流配额。[^2]
+
+还可以通过 PkgTemplates.jl 的[插件](https://juliaci.github.io/PkgTemplates.jl/stable/user/#Plugins-1)启用更多功能，如文档构建、代码覆盖率统计、格式化检查等。使用 `Template(..., interactive=true)` 可在交互模式下选择所需插件。
+
+## 代码风格
+为使代码易于阅读，建议遵循统一的代码风格规范。官方[风格指南](https://docs.julialang.org/en/v1/manual/style-guide/)比较简短，大多数人会使用第三方规范，如 [BlueStyle](https://github.com/JuliaDiff/BlueStyle) 或 [SciMLStyle](https://github.com/SciML/SciMLStyle)。[^2]
+
+[JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) 是 Julia 文件的自动格式化工具。在仓库根目录添加 `.JuliaFormatter.toml` 文件并指定风格，然后调用：
+
+```julia-repl
+julia> using JuliaFormatter
+julia> JuliaFormatter.format(MyAwesomePackage)
+true
+```
+
+VSCode 的默认格式化功能即基于 JuliaFormatter.jl 实现。也可通过 [julia-format action](https://github.com/julia-actions/julia-format) 在 GitHub pull request 中自动格式化代码。
+
+## 代码质量
+除格式之外，还有更多维度的代码质量检查工具。[^2]
+
+[Aqua.jl](https://github.com/JuliaTesting/Aqua.jl) 提供一系列自动检查，涵盖未使用的依赖、方法二义性等问题，建议在测试中包含：
+
+```julia-repl
+julia> using Aqua, MyAwesomePackage
+julia> Aqua.test_all(MyAwesomePackage)
+```
+
+[JET.jl](https://github.com/aviatesk/JET.jl) 是一个静态分析工具，通过类型推断在不运行代码的情况下检测错误和潜在问题，提供错误分析和优化分析两种模式：
+
+```julia-repl
+julia> using JET, MyAwesomePackage
+julia> JET.test_package(MyAwesomePackage)
+Test Passed
+```
+
+[ExplicitImports.jl](https://github.com/ericphanson/ExplicitImports.jl) 帮助消除泛化导入，明确每个名称的来源，增强代码对依赖项名称冲突的鲁棒性。
+
+## 版本兼容性
+Julia 社区采用[语义化版本控制](https://semver.org/)，每个包必须在 `Project.toml` 的 `[compat]` 节中指定依赖的版本兼容范围。可使用 REPL 中的 `]compat` 命令或 [PackageCompatUI.jl](https://github.com/GunnarFarneback/PackageCompatUI.jl) 来初始化这些范围。[^2]
+
+随着依赖包发布新版本，[CompatHelper.jl](https://github.com/JuliaRegistries/CompatHelper.jl) GitHub Action 会自动监控并提交 PR 更新 `Project.toml`。[Dependabot](https://docs.github.com/en/code-security/dependabot) 则可监控 GitHub Actions 本身的依赖更新。两者均是 PkgTemplates.jl 的默认插件。
+
+## 可重现性
+获得一致且可重现的实验结果对科学研究至关重要。[DrWatson.jl](https://github.com/JuliaDynamics/DrWatson.jl) 是一个通用的实验管理工具箱，提供规范化运行和复现实验的功能。[^2]
+
+其他常用工具：
+- [StableRNGs.jl](https://github.com/JuliaRandom/StableRNGs.jl)：确保随机数流在不同 Julia 版本之间保持一致
+- [DataDeps.jl](https://github.com/oxinabox/DataDeps.jl)、[DataToolkit.jl](https://github.com/tecosaur/DataToolkit.jl)：管理非代码资产（数据集等）的下载与绑定
+- [PkgCite.jl](https://github.com/SebastianM-C/PkgCite.jl)：生成依赖包的学术引用信息
+- [Zenodo](https://zenodo.org/)：为包分配 DOI，便于学术引用
+
+## 互操作性
+[Compat.jl](https://github.com/JuliaLang/Compat.jl) 是保证与旧版 Julia 兼容的最佳工具。[^2]
+
+Julia 1.9 起支持[包扩展（Package Extensions）](https://pkgdocs.julialang.org/v1/creating-packages/#Conditional-loading-of-code-in-packages-(Extensions))，可根据环境中是否存在特定包来覆盖特定行为，实现包之间的互操作。[PackageExtensionTools.jl](https://github.com/cjdoris/PackageExtensionTools.jl) 简化了扩展的设置流程。
+
+Julia 生态系统也与其他编程语言良好协作：
+- C 和 Fortran：Julia 原生支持
+- Python：[CondaPkg.jl](https://github.com/cjdoris/CondaPkg.jl) + [PythonCall.jl](https://github.com/cjdoris/PythonCall.jl) 组合
+- R：[RCall.jl](https://github.com/JuliaInterop/RCall.jl)
+
+更多语言互操作包可在 [JuliaInterop](https://github.com/JuliaInterop) 组织中找到。
+
+## 协作规范
+包规模增大后可能需要团队合作。[SciML ColPrac](https://github.com/SciML/ColPrac) 提供了一套被广泛采用的协作规范。同时，如果你喜欢某个 Julia 包，也非常欢迎通过提交 issue 或 pull request 来[参与贡献](https://julialang.org/contribute/)。[^2]
+
 ## 最佳实践
 包应该避免改变自己的状态（写入包目录中的文件）。一般来说，包不应该假定它们位于可写的位置，甚至不应该假定它们位于稳定的位置（例如，如果它被捆绑到一个系统映像中）。为了支持 Julia 包生态系统中的各种用例，Pkg 开发人员创建了许多辅助包和技术，以帮助包作者创建自包含的、不可变的和可重定位的包：
 
@@ -116,7 +192,5 @@ Julia 1.5 以后，[Scratch](../packages/scratch.md)提供了*临时空间*的
 ### Preferences
 Julia 1.6 以后，`Preferences` 允许包读写首选项到顶级的 `Project.toml`。这些首选项可以在运行时或编译时读取，以启用或禁用包行为的不同方面（以前，包会将文件写入到它们自己的包目录中以记录由用户或环境设置的选项，但现在不鼓励该行为）
 
-## 参阅
-- [Modern Julia Workflows](https://modernjuliaworkflows.org/)
-
 [^1]: https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/
+[^2]: [Modern Julia Workflows - Sharing your code](https://modernjuliaworkflows.org/sharing/) by G. Dalle, J. Smit, A. Hill（CC BY-SA 4.0）

docs/workflow/documentation.md

@@ -0,0 +1,62 @@
+# 文档与文学式编程
+## 文档字符串
+无论代码多么完善，缺乏文档都会让他人（甚至日后的自己）难以使用。为函数、类型等编写文档字符串 **docstring** 应该成为一种习惯，用户可以通过 REPL 的帮助模式（`?`）查询它们。[^1]
+
+```julia
+"""
+    myfunc(a, b; kwargs...)
+
+一句话描述函数的用途，紧跟在（缩进的）签名之下。
+
+如有必要，在此处补充更多说明。
+"""
+function myfunc end
+```
+
+[DocStringExtensions.jl](https://github.com/JuliaDocs/DocStringExtensions.jl) 提供了若干快捷方式，可自动生成签名、字段列表等常见内容，减少 docstring 的编写工作量。
+
+## Documenter.jl
+包的文档不限于 docstring，还可以包含高级概述、技术说明、示例和教程等。[Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) 允许你基于 `docs/` 子目录中的 Markdown 文件构建完整的文档网站，其[官方文档](https://documenter.juliadocs.org/stable/)本身就是极好的参考范例。[^1]
+
+本地构建文档：
+
+```julia-repl
+julia> using Pkg
+julia> Pkg.activate("docs")
+julia> include("docs/make.jl")
+```
+
+使用 [LiveServer.jl](https://github.com/tlienart/LiveServer.jl) 在本地实时预览并自动更新文档网站（类似 Revise.jl 的热更新效果）：
+
+```julia-repl
+julia> using LiveServer
+julia> servedocs()
+```
+
+通过在 [PkgTemplates.jl](https://github.com/JuliaCI/PkgTemplates.jl) 中选择 [Documenter 插件](https://juliaci.github.io/PkgTemplates.jl/stable/user/#PkgTemplates.Documenter)，可以自动配置 `docs/` 目录内容及 GitHub Actions 工作流，将文档部署到 [GitHub Pages](https://pages.github.com/)。
+
+有用的 Documenter.jl 插件：
+- [DocumenterCitations.jl](https://github.com/JuliaDocs/DocumenterCitations.jl)：从 BibTeX 文件插入学术引用
+- [DocumenterInterLinks.jl](https://github.com/JuliaDocs/DocumenterInterLinks.jl)：跨文档交叉引用（Documenter 和 Sphinx）
+
+若需要替代方案，可以尝试 [Pollen.jl](https://github.com/lorenzoh/Pollen.jl)；[Replay.jl](https://github.com/AtelierArith/Replay.jl) 则可将终端操作录制为 ASCII 视频，适合制作教程演示。
+
+## 文学式编程
+科学软件往往难以理解，仅靠代码本身可能无法清晰传达思路。文学式编程将代码与文本、公式、图像交织在一起，适合编写技术文档或学术文章。[^1]
+
+### Literate.jl
+[Literate.jl](https://github.com/fredrikekre/Literate.jl) 允许在普通 Julia 脚本中以特定格式书写注释，并将其转换为 Markdown 文档、Jupyter Notebook 或 Documenter.jl 页面等多种格式。[Books.jl](https://github.com/JuliaBooks/Books.jl) 适合撰写较长的技术书籍。
+
+### Quarto
+[Quarto](https://quarto.org/) 是一个开源的科学和技术出版系统，支持 Python、R 和 Julia。Quarto 可将 Markdown（`.md`）、Quarto Markdown（`.qmd`）和 Jupyter Notebook（`.ipynb`）渲染为多种格式：
+
+- 文档：Word、PDF、HTML
+- 演示文稿：Reveal.js、PowerPoint、Beamer
+- 网站、博客、书籍
+
+Julia 1.5+ 支持[原生 Julia 引擎](https://quarto.org/docs/blog/posts/2024-07-11-1.5-release/#native-julia-engine)，无需依赖 Python 即可执行代码块。内容可发布到 GitHub Pages、Netlify、[Quarto Pub](https://quartopub.com/) 等平台。
+
+### PlutoPapers.jl
+[PlutoPapers.jl](https://github.com/mossr/PlutoPapers.jl) 在 Pluto.jl Notebook 中直接提供类 LaTeX 样式的交互式论文排版，将计算文档与出版级论文之间的差距缩到最小。
+
+[^1]: [Modern Julia Workflows - Sharing your code](https://modernjuliaworkflows.org/sharing/)