DDoc 输出中更丰富的颜色和排版答案

【问题标题】：Richer Coloring and Typesetting in DDoc OutputDDoc 输出中更丰富的颜色和排版
【发布时间】：2013-09-07 11:09:55
【问题描述】：

我可以让我的 DDoc-marked-up D 程序生成的 HTML 页面使用更丰富的颜色和排版吗？默认为黑白。

我目前称 DMD 为

dmd -debug -gc -unittest -D -Dd$OUTPUT_DIR

【问题讨论】：

标签： syntax-highlighting d typesetting text-coloring ddoc

【解决方案1】：

好吧，您可能应该通读http://dlang.org/ddoc.html 以获取一些详细信息，但最终，您需要的是一个告诉它如何呈现页面的css 文件。这可以通过DDOC 宏来设置。

我建议看一下https://github.com/D-Programming-Language/dlang.org，其中包含 dlang.org 的代码 - 包括 ddoc 内容。特别是，您想获取 std.ddoc 以及 css、images 和 js 文件夹（如它们都被 std.ddoc 引用）。如果您随后将 std.ddoc 作为文档构建的一部分提供给 dmd，并将这些文件夹放在文档的父目录中，则生成的文档最终应该看起来像 dlang.org 上的文档。如果您想将文件夹放在其他位置，只需在 std.ddoc 中调整它们的路径即可。

如果您想更改文档的外观，只需相应地调整 std.ddoc 和 css 文件。那时，您正在处理的是 html 和 css 内容，因此您必须了解它们是如何工作的，以便对 std.ddoc 中的宏或css 文件本身。当然，如果你想对 js 文件做任何事情，你需要了解 javascript。如果你愿意，你可以去掉所有的 js 和图像。它们只是用于 dlang.org 的东西，但同样，您必须了解 html 和朋友如何工作才能知道如何处理它。我对这些都不是特别精通，所以当我生成文档时，我通常只对 dlang.org 使用的内容进行少量更改，但我通常一直在寻找的只是获得更清晰的颜色而不是默认的，而不是任何特定的。

很抱歉，我不能比这更具体或更有帮助，但我所做的最好的事情就是偶然发现它足以让页面看起来像 dlang.org，因为我对 Web 开发几乎一无所知.希望这会为您指明正确的方向。

您可能想要查看的其他内容是ddox，它使用 ddoc cmets 生成比 dmd 更好看的文档。 dlang.org 很可能会在不久的将来某个时候切换到使用 ddox 生成的文档（一些细节仍然需要整理，所以我不知道确切的时间，但这是目前的计划）。因此，使用 ddox 最终可能会比使用 dmd 生成文档更普遍。

【讨论】：

【解决方案2】：

您可以创建自己的 .ddoc 配置文件，在其中覆盖或创建新的 ddoc 宏以使用类名和 ID。然后，您可以使用 CSS 设置页面样式。

包含自定义 CSS 的示例 .ddoc 文件，请注意 head HTML 部分中的 theme.css 文件：

DDOC = <!DOCTYPE HTML>
<html>
    <head>
        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
        <link type="text/css" href="theme.css" rel="stylesheet" media="all" />
        <title>$(TITLE)</title>
    </head>
    <body>
        <h1>$(TITLE)</h1>
        $(BODY)
    </body>
</html>
H2 = <h2>$0</h2>
H3 = <h3>$0</h3>
STRONG = <strong>$0</strong>
EM = <em>$0</em>
DDOC_DECL = $(H2 $0)
DDOC_DECL_DD = <div class="declaration-description">$0</div>

DDOC_CLASS_MEMBERS = <div class="class-members">$0</div>
DDOC_SUMMARY = $(P $0)
DDOC_DESCRIPTION = $(P $0)

DDOC_MEMBERS = <div class="members">$0</div>
DDOC_ENUM_MEMBERS = <div class="enum-members">$0</div>
DDOC_MODULE_MEMBERS = <div class="module-members">$0</div>
DDOC_STRUCT_MEMBERS = <div class="struct-members">$0</div>
DDOC_TEMPLATE_MEMBERS = <div class="template-members">$0</div>

此文件应保存在某处并添加到 sc.ini 文件（对于 Windows）或 dmd.conf 文件（对于 Mac/Linux），如下所示：

DDOCFILE=myproject.ddoc

然后当您下次使用 -D 进行编译时，会从自定义 ddoc 宏而不是内置的东西和 viola 中读取 HTML，这样您就有了与 CSS 一起使用的可样式化的类名和 id。

这里是使用自定义样式表和宏的漂亮文档的预览：http://htmlpreview.github.io/?https://github.com/kalekold/dunit/master/docs/dunit/toolkit.html

HTML 文件：https://github.com/nomad-software/dunit/tree/master/docs/dunit

完整的 ddoc 宏列表可以在这里找到：http://dlang.org/ddoc.html

【讨论】：