问题

• 我想把我的代码和我的文档放在同一个地方。

• 我想将表示层与我的文档内容分开。

• 随着流程的发展,我希望能够灵活地将文档发布到各种端点和格式,而不会影响我的内容。

• 我想为不能完全自动化但仍包含其本机格式的脚本和其他代码的事物编写可靠的运行手册。

文档是开发人员生活中如此重要的一部分。我认为我们经常认为这是理所当然的,而且在许多项目中都是事后才想到的。

然而,当我考虑我的工作时,我知道我并没有经常重新发明轮子😀。

我所做的大部分工作都是建立在他人工作的基础上的。

当我使用工具时,我正在阅读文档并将其作为完成工作的基础。

当我使用我的笔记和博客文章作为参考时,我使用的是我的非正式版本的知识收集。

INVEST 为你身后的人记录你的工作。

你没有时间去做,你在工作的时候抽出时间去做,作为你工作的一等公民,而不是事后的想法。

想想你不得不挖掘答案并拯救别人的所有时间。

您编写代码和记录文档的时间不是为了自己,而是为了后面的人。

Asciidoctor

我在 Markdown 的 Asciidoctor 文档格式中找到了一个快乐的解决方案。

你可以去谷歌这个以获得更多的理解,但我决定除了非常简单的基本笔记和博客文章之外,我现在选择 Asciidoctor。

为什么使用 Asciidoc 格式而不是 markdown 取决于技术文档的需求。

以下是我发现 Asciidoc 格式值得学习的一些关键原因:

• 我可以使用简单的include::file[]语句引用代码文件,而 Markdown 则需要我将代码直接嵌入为代码块。

• 我可以从 csv 文件生成表格,进一步帮助我自动刷新呈现到表格显示的基础数据

• 与 Markdown 相比,我可以更干净、更可控地创建表格,甚至允许嵌套表格用于复杂的流程文档。

• 使用简单语句(如IMPORTANT: foo)的不带扩展名的自动警告标注

介绍

由于我使用的通用文档系统是 Confluence,因此我决定利用令人难以置信的 confluence-publisher 项目,它使整个过程变得轻而易举。

在此处查看 repo 和链接文档:Confluence Publisher

将来,如果我不使用 Confluence,我会探索通过 Hugo 渲染为静态网站(这就是生成此网站的内容)或重新访问 Antora,并可能以编程方式将我的内容合并为 Atora 所需的格式。

使用 Docker

由于 Asciidoc 是用 Ruby 编写的,因此使用 docker,您将不必处理依赖关系的噩梦,尤其是在 Windows 上。

$RepoDirectoryName = 'taco-ops-docs'
echo "🌮🌮🌮🌮🌮🌮🌮🌮🌮🌮🌮🌮🌮"
echo "Running confluence publisher 🌮"
echo "📃 Publishing $RepoDirectoryName repo contents"

docker run --rm -v $BUILD_SOURCESDIRECTORY/$RepoDirectoryName/docs:/var/asciidoc-root-folder -e ROOT_CONFLUENCE_URL=$ROOT_CONFLUENCE_URL \
-e SKIP_SSL_VERIFICATION=false \
-e USERNAME=$USERNAME \
-e PASSWORD=$PASSWORD \
-e SPACE_KEY=$SPACE_KEY \
-e ANCESTOR_ID=$ANCESTOR_ID \
-e PUBLISHING_STRATEGY=$PUBLISHING_STRATEGY \
confluencepublisher/confluence-publisher:0.0.0-SNAPSHOT
echo "📃 Publishing $RepoDirectoryName repo contents finished"

是的,我知道。调试时我对阅读日志消息感到厌烦,所以我的新年前提是添加一些表情符号以增加多样性。

不要评判。 😁

分布式文档结构

因此,上述方法对于单个 repo 来说非常棒。

我想通过解决分布式文档的这个问题来将它提升到一个不同的层次。

分布式我的意思是,我不想将所有文档包含在单个“wiki”样式的存储库中,而是想从我选择的存储库中获取文档并呈现它。

这将允许相关的文档包含在与其相关的存储库中。

例如,如果我想以以下结构呈现文档怎么办:

** General Documentation**
taco-ops-runbook
---> building-tacos
--------> topic.adoc
---> eating-tacos
--------> topic.adoc
---> taco-policies
--------> topic.adoc
---> taco-as-code
--------> topic.adoc

** Repo Oriented Documentation**
github-repos
---> taco-migration
--------> category-1
------------> topic.adoc
------------> topic.adoc
--------> category-2
------------> topic.adoc
------------> topic.adoc
---> taco-monitoring
--------> category-1
------------> topic.adoc
------------> topic.adoc
--------> category-2
------------> topic.adoc
------------> topic.adoc

当前唯一找到的解决方案是Antora。

Antora 非常有前途,非常适合软件开发团队采用更规范的文档方法。

我面临的限制是结构的复杂性和刚性。

要让 Antora 生成一个漂亮的文档站点,您必须确保文档的结构更加复杂。

例如,文档可能低于docs/modules/ROOT/pages/doc.adoc,并且也有一个nav.adoc文件。

虽然这保证了一个可靠的解决方案,但如果您的团队甚至从未做过降价,那么改造或期望采用可能会很棘手。

Azure DevOps 管道

我最终使用了 Azure DevOps 管道(当然是 YAML 🤘),它提供了一种很好的简单方法来完成这项工作。

首先,为了正确链接,您应该遵循 Azure DevOps 给出的关于创建使用 OAUTH 的Github 服务连接的说明。

这将确保您的设置不会脆弱并使用您的访问令牌。

须知

• 确保您使用此处显示的文档格式以正确呈现在 Confluence 中。您需要在 doc/folder 中匹配名称,以便它知道呈现子页面。

** Repo Oriented Documentation**
taco-ops-repo
README.adoc  -- optional, but I always include for landing page, and point to the docs folder using link:./docs/myrepo.adoc
---> [docs]
------> [resources]  -- optional, but keeps the scripts organized and consistent, or any images
------> process.adoc
------> another-process.adoc
---> taco-ops-repo.adoc

• 使用include::./resources/_myscript.ps1[]包含您的脚本。如果执行多个 repos,您可能必须测试该相对路径问题。

• 确保您的非 asciidoc 内容在标题名称中以下划线开头。我不喜欢这样,但这是 confluence-publisher 的要求。这确保它不会尝试呈现为页面。

• 目标目录(祖先)中的任何内容都会在此过程中被清除。我建议您为此创建一个专用的汇合空间,以最大程度地降低风险并禁用手动编辑。

Microsoft 托管代理中的 Docker 命令

我没想到 docker 命令可以在 Azure DevOps 代理中运行,因为我认为嵌套虚拟化不起作用。但是,它工作得很好。考虑使用 Azure DevOps yaml 管道来运行你的 docker 命令,你朝着更好的构建过程迈出了一步。