Syslab使用手册 —— Matlab 样式的 julia 文档

综合讨论区
1

https://tongyuan.cc/help/SyslabHelp.html

他有很多的工具箱，使用了私有的包。
纯 julia 的用户看基础和数学的部分就足够了。

Matlab 的用户会比较熟悉这种文档的组织方式。

基础工具箱

  • 输入命令
  • 数组
  • 数据类型
  • 集合容器
  • 初等运算和初等函数
  • 流程控制
  • 环境和设置
  • 编程
  • 数据导入和分析
  • Syslab 运算符和特殊字符

数学工具箱

  • 初等数学
  • 线性代数
  • 随机数生成
  • 插值
  • 数值积分和微分方程
  • 傅里叶分析和滤波
  • 稀疏数组

举例 sin

3 个赞
2

我还挺喜欢这种每个函数拥有单独文档页的样式。

我尝试给 julia 函数的文档字符串加入更多的示例，不过大家更倾向与对 REPL 中的帮助保持简洁。

JuliaLang/julia 中也已经有提出要拆分单独的文档页面的 issue 了

除开具体的实现，这个需要 GitHub - JuliaDocs/Documenter.jl: A documentation generator for Julia. 的支持，需要有人去推进。
使用现有的文档系统我做了一些模仿，发现了一些问题。

https://inkydragon.github.io/EndlessTesting.jl/dev/Base.Math/Trigonometry/Sine/sin/

julia 的惯用模式是多重分派，很容易给一个已经存在的函数添加新的、不同参数类型的方法。
这也意味着，对于一个函数，julia 的文档需要更多的示例。

即使大多数示例都是显然的，但总会有一些不那么明显的例子。
例如：输入参数为矩阵时的 sin 和逐元素计算矩阵的 sin。

除了手动列出所有方法的示例外，另一种可能是，推荐给新增的方法都加上文档字符串，并附带上一些示例。然后通过文档生成工具汇总在一起。

以上是一些零散的想法。
总的来说 julia 的文档编写和组织还有很大的改进空间。
同元给 julia 社区开了做出了一个好的示范。

对于 julia 的文档

2 个赞