Более богатая окраска и набор в выводе DDoc

Могу ли я сделать сгенерированную HTML-страницу из моей D-размеченной Doc-программы более насыщенной раскраской и набором шрифтов? По умолчанию черно-белый.

Я в настоящее время называю DMD как

dmd -debug -gc -unittest -D -Dd$OUTPUT_DIR
Источник

2 ответа

Решение

Что ж, вам, вероятно, следует прочитать 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, так как я почти ничего не знаю о веб-разработке. Надеюсь, это покажет вам правильное направление.

Что-то еще, на что вы можете обратить внимание, это ddox, который использует комментарии ddoc для создания документации, которая выглядит лучше, чем dmd. И вполне вероятно, что dlang.org перейдет на использование документации, сгенерированной ddox, когда-нибудь в относительно ближайшем будущем (некоторые детали еще предстоит выяснить, поэтому я не знаю, когда именно, но это текущий план). Таким образом, использование ddox в конечном итоге может стать более распространенным, чем использование dmd для генерации документации.

Источник

Вы можете создать свой собственный файл конфигурации.ddoc, в котором вы переопределите или создадите новые макросы ddoc для использования имен классов и идентификаторов. Затем вы можете оформить страницу с помощью CSS.

Пример файла.ddoc, содержащего пользовательский CSS, обратите внимание на theme.css файл в head HTML раздел:

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

Затем в следующий раз вы будете использовать -DHTML читается из пользовательских макросов ddoc, а не из встроенного материала и альта, у вас есть стилистические имена классов и идентификаторы для использования с CSS.

Вот предварительный просмотр красивой документации с использованием пользовательской таблицы стилей и макросов: 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

Источник
Другие вопросы по тегам