Генерация списка символов в ddoc (с дублированием)

Question

У меня довольно большая отдельная страница документации, и я хочу создать список символов (Jump to: на документах Phobos, смотрите std.compiler) с dub --build=ddoc потому что его там нет по умолчанию ( текущая страница документации)

Я бы не хотел включать в код список всех символов со ссылками по понятным причинам.

Я знаю, что это возможно с ddox или javascript, но есть ли способ сделать это, используя только vanilla ddoc, чтобы усилия по обслуживанию могли быть сведены к минимуму? Спасибо

Редактировать: я хочу сгенерировать листинг как для глобальных символов, так и для членов классов и поставить таблицу рядом с классом.

Answer 1

Ddoc - это макросистема. Это просто заменяет одну вещь чем-то другим. Компилятор определяет определенные макросы для вас (которые вы можете переопределить), а для фактического создания страницы документации с использованием ddoc компилятор берет комментарии документации из модуля, его список документированных символов и т. Д. И в основном генерирует страницу.dd, например вы бы имели при создании чего-то вроде веб-сайта dlang.org. Это куча текста с разметкой ddoc. Эта разметка ddoc затем заменяется тем, что определено для замены этих макросов ddoc. По умолчанию это набор html, предназначенный для создания веб-страницы, но эти макросы могут быть переопределены для создания html, отличного от заданного по умолчанию, или для создания чего-то совершенно другого, например, латекса.

Однако, в конечном итоге, все, что вы получаете, это эквивалент страницы.dd, где вы можете повлиять на результаты, переопределив макросы и, таким образом, переопределив, как один фрагмент текста преобразуется в другой. У вас нет нулевой возможности перебирать список символов или делать что-либо особенно полное. Все, что вы получите, это расширение макроса.

Вот почему dlang.org использует javascript для генерации перехода к ссылкам, и именно поэтому процесс сборки для dlang.org на самом деле имеет небольшую D-программу, которая запускается для генерации ddoc для панели навигации со списком модулей. ddoc не может ничего из этого сделать. И именно поэтому такой инструмент, как ddox, использует вывод json от компилятора, чтобы получить список символов и информацию о документации, а также создать свою собственную вещь.

Так что нет, вы не можете делать что-то вроде того, что вы пытаетесь сделать с помощью стандартного ddoc. Действительно, единственные варианты - использовать javascript, чтобы браузер мог манипулировать результатом при просмотре документа, манипулировать и / или генерировать ddoc с помощью внешней программы или генерировать документацию с помощью совершенно другого инструмента, такого как ddox.

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

Документация Ddoc: https://dlang.org/spec/ddoc.html

Ниже перечислены некоторые альтернативные генераторы документации (которые могут использовать или не использовать ddoc): https://wiki.dlang.org/Open_Source_Projects