发布DocBlock v0.1

自动生成配置文件技术内容的工具

许多个月前,我的一位技术作家同事抱怨说,他们如何努力跟上公司当时的频繁发布。 盘子里有多个产品,每个产品都有多个配置文件(有时编号超过10个)。 尽管配置文件在每个产品中重叠,但是由于公司在其上构建了组件化平台,因此理论上每个产品可以具有使用这些配置文件的组件的不同发行版。 所有这些都必须记录在可读(且最重要是可用)的技术内容中。

他们遵循的手动过程中存在许多问题。

  1. 大多数配置文件缺少描述性注释,这些注释可以帮助潜在的用户或技术作家。
  2. 即使有描述性评论,评论本身也缺乏适当的上下文。 对于技术作家来说,很容易会误解撰写评论的开发人员试图表达的内容。
  3. 技术作家经常会发现自己没有某些配置元素所代表的深刻的技术知识。
  4. 弄清楚某个配置元素的详细细节可能意味着几天,甚至有时是数周的与开发人员团队来回交流。
  5. 技术写作团队无法简单地通过频繁的发布周期有效地进行横向扩展。

他们希望使这一过程自动化,并创建一个涉及最少的人机交互的过程,以生成有意义的内容。

作为开发人员(和好朋友)的我认为我可以提供帮助。

问题

在技​​术内容方面,应该填补的空白是开发人员所拥有的深入而准确但又没有口齿的技术知识 与技术作家所拥有更广泛的领域相关但较浅的技术知识和出色的写作技能之间的差距。 不幸的是,仅将技术作者和开发人员放在同一个房间中是不会这样做的。 由于沟通错误,知识水平差异或(不幸的是)狂妄自大,这种差距在大多数情况下仍是一个差距。

将配置文件添加到产品时,由开发人员编写实现,从而知道实际的目的,参数和配置选项的用法。 因此,必须在开发时完成对配置文件应做的任何文档编制。

这不是一个新概念。 从代码级别到API方法定义级别的API文档都是通过这种方式处理的。 代码注释(如果结构化)可以解析为可读内容。 像Swagger这样的DSL提供了在编写API方法时记录其方法的机制。 然后,这些详细信息将自动转换为文档工件,例如HTML或Markdown文件。 配置文件也应如此。

答案

这是启动项目的主要理由,当时我编写的代码名为“ docblock”。 目的是介绍一种方法,使开发人员在开发时将结构化注释写入配置文件中,然后对其进行解析以自动生成文档。 这将是一个小的二进制工具,一堆配置文件将被输入到该文件中,以输出Markdown或HTML。

在开发该工具时,作为我的宠物项目,我感兴趣的用例(我的技术作家同事很想解决)正在转换基于XML的配置文件。 输出将是Markdown,它也可以生成HTML内容。

文档注释的结构是下一个要讲的故事。 我可以

  1. 在文档注释中提供一组预定义的“字段”,供开发人员填写
  2. 让每个用例(例如:公司,项目,组件)决定评论的结构

第二种方法有点复杂,但是可以解决大多数用例。 它产生了一种称为解析器语言的概念。

docblock中的解析器语言是文档注释的格式。 Docblock将使用这种用户定义的格式来翻译评论并从评论中生成内容。

docblock随附的standard解析器语言定义如下。

遵循上述格式的文档注释如下所示。

  1. @doc定义特定注释为文档注释,并且docblock应该开始查找定义的字段。 该字符串称为解析器格式的梯形失真
  2. 接下来是元素描述。 这应该描述特定配置元素的目的和用法。
  3. @type是上述解析器格式的用户定义字段。 在这种情况下,它代表特定配置元素期望的值的类型
  4. @possible_values也是用户定义的字段。 它代表可以作为配置元素放入的可能值的列表。 这对于需要一组值而不是一组开放值的配置选项很有用。 (例如: noneallsingle

显而易见,docblock直接从JavaDoc样式代码注释中汲取了灵感。

当docblock解析以上文档注释时,生成的HTML内容如下所示。

表格渲染。 请注意,列名称与解析器格式中的值匹配。

筛选出的描述

该工具的预期涉众如下。

  1. Technical Writer Admin —该角色将决定和定义开发人员在记录配置文件时应遵循的解析器格式。
  2. 开发人员 -该角色将以先前确定的格式记录配置文件,并使用该工具验证正确的内容
  3. 团队/项目基础技术作家 -该角色将使用该工具生成文档内容。 它将执行纠正任务,例如添加未自动生成的任何其他内容,纠正格式并删除通常不需要的部分。

该代码是开源的,并获得了Apache License v2的许可。 可以在GitLab存储库中找到该代码。 第一个版本是v0.1

一段时间之后,Docblock的开发暂停了,这仅仅是因为我没有足够的时间来组织编程。 当我回到源代码时,该工具最初为之开发的相关性故事已经开始流行。 该组织正在转向基于非XML的配置文件。 无论如何,我必须完成开发的第一个迭代并达到里程碑版本。 v0.1是docblock的第一次迭代(换句话说,这是对一年多以前问到的问题的解答)。

该工具是使用Go开发的。 为什么去? 因为这是我可以编码的唯一语言,所以可以生成独立的二进制文件。 我想从现在的学生发展成为经验丰富的Go用户。

编写代码的方式是,将来可以轻松引入输入配置文件类型和输出内容类型。 但是,目前仅支持将XML作为输入类型,并且仅将Markdown (以及Markdown生成的HTML )作为输出生成。

我计划将YAML和TOML作为输入类型添加为即时开发(这意味着docblock尚不能自动生成其自己的配置文档)。 但是,由于YAML解析器通常不会在对象模型中包含注释,因此,像XML一样转换起来并不容易。

尽管docblock可以处理XML配置文件自动化的预期(尽管范围很窄),但是其他用例可能找不到它直接适用,至少现在还没有。 但是,任何输入或推荐的好/不好的经验,将不胜感激。