R#语言的记事本渲染工具

https://github.com/rsharp-lang/Rnb

之前使用Python脚本进行编写代码的时候，十分的羡慕Python脚本可以基于ipynb记事本进行文档化的编码。在之前R#脚本是缺少相关的代码库模块将可执行的R#脚本渲染成可视化文档。但是经过几天的开发工作时候，现在R#脚本编程已经具备有了文档化编程的基本框架了。

在这里我来介绍一下这个最近开发完成的进行通过R#文档化编程的框架基础：R#脚本的文档渲染器引擎。

文档渲染器脚本

在介绍对R#脚本的文档化编写之前，我们先来学习一下进行文档化渲染的相关的R#语言之中的工具api。首先是来介绍一个命令行脚本renderHtml.R，这个脚本用于调用相关的文档渲染引擎，将目标R#脚本文件渲染为html文档。

require(Rnotebook);

#' title: Rendering R# notebook script
#' 
#' author: xieguigang <xie.guigang@gcmodeller.org>
#' description: A cli pipeline R# script for run rendering 
#'    of the R# notebook script into html help document.
#' 

[@info "The R# source script file its filepath."]
[@type "filepath"]
const notebook as string = ?"--notebook" || stop("no notebook source file is specified!");
[@info "The output file path of the html document file that rendered from the given R# source script file."]
[@type "filepath"]
const htmlfile as string = ?"--output" || `${dirname(notebook)}/${basename(notebook)}.html`;

engine::parse(notebook)
|> pipHtml
|> writeLines(con = htmlfile)
;

嗯，其实这个脚本代码也是一个命令行帮助文档自述的R#脚本：这个脚本既可以执行相关的具体功能代码，也可以通过--help命令将自身代码以文档化的形式将使用帮助信息显示在命令行之中，例如：

如果我们将上面的脚本代码中的注释部分，以及命令行参数读取部分的代码都去除掉，我们可以发现，其实整个用于文档渲染的命令行脚本的内容其实非常的简单：整个流程就是加载写好的Rnotebook程序包，然后调用渲染引擎解析目标R#脚本，然后渲染为html文档，最后将html文档写到目标结果文件之中即可。

require(Rnotebook);

# ignores other code, just keeps the mainframe code
engine::parse(notebook)
|> pipHtml
|> writeLines(con = htmlfile)
;

R#脚本的文档化编写

其实进行R#脚本的文档化编写操作是非常的简单的。你只需要按照一定的规则正常的编写R#脚本即可。下面我们来介绍一下在进行R#脚本的文档化编写的两大主要部分的一些语法要求吧：

markdown文档

在R#脚本的文档化渲染之中，默认只支持markdown文档格式。所有的顶层注释代码都是markdown文档，所以我们只需要基于markdown语言，进行相应的注释代码块的编写即可。但是在这里和普通的R#脚本的注释编写有一个小小的不同之处就是，markdown文档与代码块文档的交界之处必须要有一个;分号作为分隔符才行。例如：

# # Demo test for markdown
# This is a paragraph in the markdown document.
# ## H2 title
# This is another paragraph in the markdown document.
# ### DEMO1: Markdown list
# Here is a list of supported features in R# notebook:
#
# + markdown document
# + code block
# + image output of the code block
#
# ### DEMO2: Table test
# Create a table in document just like what you do in the markdown document:
#
# |Features                      |supported|
# |------------------------------|---------|
# |markdown document             |yes      |
# |code block                    |yes      |
# |image output of the code block|yes      |
#
# ### DEMO3: Code test
# Yes, you can write a code block in markdown document block:
# ```r
# print("Hello world!");
# ```
# > But this code block will not be evaluated
;

千万要注意哦，在上面所展示的注释代码块的最末尾，应该是通过一个分号来进行结束的。将上面的注释代码块保存为脚本文件，然后通过文章开头的脚本进行文档渲染，可以得到如下所示的文档结果：

实际的R#功能代码块

在进行文档化编写的时候，执行实际功能的R#代码块就和书写普通的R#脚本代码一样的进行代码文本的书写工作即可。只不过，这个所书写的代码块的前后多了一对一一对应的标签用来进行分隔。这个标签的语法与VisualBasic.NET语言之中的region标签是保持一致的。例如

# # R# code block demo 
# One code block in the R# notebook should be start with a 
# tag: ``region "name"``, and then should be end with a tag:
# ``end region``. And also the code block should be end with
# a individual semicolon symbol.
#
# syntax example as:
#
# ```r
# #region "block name"
# ...
# #end region
# ;
# ```
;

#region "Rscript code demo"
const word as string = ["World", "R#", "User"];

# print string contents at here will also be
# rendered on the html document!
print(`Hello ${word}!`);
#end region
;

上面的代码块将会被文档渲染引擎渲染为：

渲染图片

你是不是会惊奇的发现，文档渲染引擎在生成对应的代码文档的时候，还会执行对应的代码，将代码块的执行结果输出到文档之中。那我们是不是可以在代码中插入绘图函数，将代码所绘制的图表也一同渲染在代码文档之中呢？我们来试一下plot函数：

# # Notebook charting demo
#
# the image outputs of the ``R#`` charting plot code will be encoded as
# base64 string and then embbled as image tag in the generated
# html document code.
;

#region "image test"

# scatter plot test
const size = 225;
const x = runif(size);
const y = ((x * 5) ^ 3) / 2 + x * 5 + 60;

plot(x, y + runif(size) * 13, 
  background = "white", 
  grid.fill  = "white", 
  color      = "skyblue",
  point_size = 23,
  shape      = "Triangle" 
);
#end region
;

执行一下上面的代码，嗯嗯，不错不错，R#代码所绘制的图表确实已经被显示在了我们所生成的html文档之中了：

• Author
• Recent Posts

谢桂纲

高级数据科学家 at 苏州帕诺米克

Working on Engineered bacteria CAD design on its genome from scratch. Writing scientific computing software for Tianhe & Sunway TaihuLight supercomputer. Do scientific computing programming in R/R# language, he is also the programming language designer of the R# language on the .NET runtime.

Latest posts by 谢桂纲 (see all)

• 【MZKit】简单自动化组织分区 - 2023年11月5日
• 【MZKit教程】质谱成像原始数据文件查看 - 2023年6月29日
• 生物序列图嵌入算法 - 2023年6月29日