我们讨论了很多关于将内容与其呈现分离的问题。 这些方法自 CSS 早期就存在于 Web 开发领域,并在轻量级标记语言中得到了重新解释和增强。 该技术涉及将文档的视觉和设计方面与其内容和结构分开。 这样,文档编写者可以专注于内容,同时轻松调整其呈现方式。
但我们可以更进一步,将数据与其表示解耦。 可以根据数据本身生成文档,而不是与所讨论的事物不直接相关的标记。 我们可以从应用程序运行时获取数据,然后定义其表示形式。
据了解,我们可以通过遵循数据设计来使表示有条件。 例如,如果方法描述表明它已被弃用,则将其变成警告元素。 在其他情况下,将其变成一个段落。
示例如下:
val descriptionTag = if (method.description.contains("DEPRECATED")) "warning" else "p"
xml(
"""
Method type: <font color="$font">${method.type.uppercase()}
<def title="${method.summary}">
<$descriptionTag>${method.description}</$descriptionTag>
"""
)
文档即代码的新水平
我们经常谈论将文档视为代码,但我们通常指的是有限数量的工具和实践,例如使用轻量级标记创作、将文档置于版本控制之下以及使用代码审查和 linter。 而且,我们可以从开发领域学到更多。
借助 KotlinDSL,文档成为代码的代名词,允许文档编写者利用开发人员使用的常见实践。 一些做法包括:
可扩展性
DSL的可扩展性将打破现有规则。 除了允许您添加自定义元素之外,它还支持更改 DSL 本身,这开辟了无限的可能性。
您的想象力没有限制。 一切可以在计算机上实现的事情,都可以通过文档来实现!
由于与现有 JVM 库的无缝集成,您可以组合数据源、解析和丰富内容,甚至与 Selenium 和 Cucumber 等外部工具和框架集成。
KotlinDSL 可扩展性选项的示例包括:
为什么选择科特林?
之前已经尝试过从代码生成 HTML,所以您可能想知道为什么我们选择 Kotlin 来用于文档目的?
首先css 文档流,Kotlin 具有一些中级功能,有助于创建强大的 DSL。
其次,Kotlin 因实用且适合初学者而享有盛誉。 它秉承简化日常任务的原则,确保新手能够快速轻松地掌握语言。
例如,在编写基本的“Hello, World!”时在 Kotlin 中编写程序时,初学者不会被迫使用他们不理解的概念和关键字。
以下示例比较了“Hello, World!” Java 程序与 Kotlin 程序:
爪哇:
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
科特林:
fun main() = println("Hello, World!")
在 Kotlin 中,您不需要定义类或使用 publicstaticvoid 签名。 main()函数作为入口点,可以直接使用println()输出所需的消息。 这些简单性是 Kotlin 的主要优点之一,使编写基本程序变得更容易、更愉快。
如前所述,Kotlin 与 JVM 生态系统无缝集成。 Java已有近30年的历史,拥有大量有用的工具和库。 您可以通过在构建脚本中添加一行来将此工具合并到您的工作流程中。
在选择 Kotlin 时,我们优先考虑在简单性与强大功能之间取得平衡的语言,以确保愉快且高效的开发者体验。
我需要成为一名程序员才能使用 KotlinDSL 吗?
我们经常看到文档编写者说:“我只是一个普通的技术文档编写者,不是开发人员,也不是非常精通技术!我应该如何使用它?我需要哪些编程技能才能从中受益?”
要开始使用 DSL 元素作为标记,您不需要任何编码技能或了解 DSL 的工作原理。
您仅需要对 Kotlin 有基本了解才能完成与手动操作相关的个人任务。 JetBrains Academy 的 KotlinCore⁷ 课程提供所有必要的知识。
然而,我们相信从长远来看,学习 KotlinDSL 是有价值的。 凭借其直观的语法和 IDE 支持,文档编写者可以快速掌握并更充分地利用强大的文档工具。
将这些方法合并到文档工作流程中时,您可能需要学习一些编程。 将 KotlinDSL 集成到您的工作中可以让您亲身实践专门适用于文档职责的编程。 尽管如此,技术作家可能更喜欢与文档相关的任务,而不是综合练习,例如分数估计或基本估计器构建假设课程。 据悉,学习 Kotlin 还有助于了解其他语言和生态系统。
这些方法可能并不适合所有技术作家,但对于那些编写开发人员工具内容以提高技能的人来说特别有帮助。
推理
KotlinDSL for Documentation 引入了范式转变css 文档流,使技术作家可以轻松利用编程语言的力量来创建精彩的内容。 凭借 Kotlin、IDE 支持以及 DSL 固有的可扩展性的优势,文档不再只是页面上的文字。 它成为开发过程中动态的、集成的一部分,改善协作并提供卓越的结果。
快来探索 KotlinDSL 满足您文档需求的无限可能性!
我们已经创建了一个示例项目⁸,您可以下载并试用 KotlinDSL。 如果您有任何疑问,请加入我们的 Slack,我们的专用频道是#kotlin-dsl-for-docs。
拥抱代码的力量,将您的文档提升到新的高度。
祝您写作和编码愉快!
相关链接:
1. 伦敦 APITheDocs 会议:
2.JetBrains MPS 网站:
3.类型安全构建器:
4、功能组成:
(计算机科学)
5.可读性分析工具:
6.Apache OpenNLP:
7.Kotlin核心:
8. 示例项目:
本博文英文原作者:SvetlanaNovikov、IgorKulakov
这是 Kotlin 编程语言
简单、跨平台、有趣!
发表评论