为什么RobotFramework用libdoc生成的HTML无法显示多行说明文档？

问题原因 #

Robot Framework的libdoc工具默认使用类reStructuredText的文档解析规则，同一段落内的换行符会被解析为普通空白符合并，只有空行才会被识别为段落分隔，生成新的<p>标签。你之前尝试的\n、调整缩进、修改换行符格式都不命中换行解析规则，因此不生效。

可用解决方案 #

方案1：使用Robot Framework原生强制换行语法 #

在需要硬换行的行末尾添加两个反斜杠\\，即可在同一段落内生成换行：

*** Settings ***
Documentation  
...     Testing for new lines\\
...     Here is a second one
...
...     And new paragraph\\
...     New line in the new paragraph

该方案不需要修改其他配置，直接适配默认解析规则。

方案2：切换为Markdown文档格式 #

Robot Framework 3.1及以上版本支持Markdown格式的文档解析，你可以通过两种方式开启：

• 在资源文件的*** Settings ***块中添加配置：

*** Settings ***
DocFormat    markdown
Documentation  
...     Testing for new lines  
...     Here is a second one

注意每行末尾需要加两个空格，符合Markdown硬换行语法。

• 运行libdoc命令时显式指定文档格式：

libdoc --docformat markdown .\MyResource.resource MyResoure.html

该方案支持完整Markdown语法，更适合复杂文档编写。

方案3：直接内嵌HTML换行标签 #

如果不需要兼容其他格式，也可以直接在文档中插入<br>标签实现换行：

*** Settings ***
Documentation  
...     Testing for new lines<br>
...     Here is a second one

内容的提问来源于stack exchange，提问作者Matt