Как создать разборные разделы кода в стиле rdoc?
-
05-07-2019 - |
Вопрос
Я создаю внутреннюю документацию для проекта C++, используя Doxygen.Я включаю в Doxygen исходный код методов и т. д., но из-за этого страницу сложно сканировать.Я бы хотел, чтобы он вел себя как rdoc и скрывал источник в блоке, который по умолчанию свернут.
я думал так HTML_DYNAMIC_SECTIONS
мог бы позволить мне это сделать, но, увы, в журнале изменений говорится, что эта опция влияет только на диаграммы и графики.
Возможно, я мог бы сделать это, отредактировав LAYOUT_FILE
?
В любом случае, умные люди, как мне заставить Doxygen генерировать свертываемые разделы кода?
Решение
если включение источника методов и т. д. [...] затрудняет сканирование страницы, почему бы тебе просто связь к этому (SOURCE_BROWSER = YES
) вместо включая это (INLINE_SOURCES = YES
)?это облегчит сканирование страниц и ускорит их загрузку, а исходный код по-прежнему будет доступен (за счет загрузки еще одной исходной страницы).Я думаю, зависит от того, как часто вам действительно нужен доступ к источнику.
как говорится, там является способ создания разборных разделов кода (однако вам придется изменить исходный код и перекомпилировать Doxygen):
- свертываемые разделы в HTML-выводе Doxygen отмечены двумя вложенными
<div>
с вот так:
<div class="dynheader"><div class="dynsection">
[collapsible section]
</div></div>
- включенные разделы кода помечены следующим образом:
<div class="fragment"><pre class="fragment">...</pre></div>
таким образом, чтобы сделать включенные разделы кода разборными, вам необходимо либо
- изменить код, который генерирует тот
<div class="fragment"><pre class="fragment">...</pre></div>
генерировать<div class="dynheader"><div class="dynsection">...</div></div>
(и, возможно, скорректировать CSS), или - изменить javascript
initDynSections()
функция который сканирует и сворачивает складные разделы для распознавания<div class="fragment"><pre class="fragment">
как один из них.
- изменить код, который генерирует тот
реализация (или переход к SOURCE_BROWSER
Маршрут :)) оставлен в качестве упражнения для читателя.удачи!
ох, и если у тебя получится с патчем, было бы здорово, если бы ты смог представить это Дмитрию, чтобы он мог включить его в будущую версию.Спасибо!
Другие советы
Приходя сюда, используя поисковую систему по своему выбору, я просто хочу отметить, что нет необходимости изменять источник кислорода.
Когда был задан этот вопрос, у встроить чистый HTML с помощью тега htmlonly
, но с учетом этого можно создавать складываемые секции контейнера, используя функцию с именем toggleVisibility
function toggleVisibility(linkObj)
{
var base = $(linkObj).attr('id');
var summary = $('#'+base+'-summary');
var content = $('#'+base+'-content');
var trigger = $('#'+base+'-trigger');
var src=$(trigger).attr('src');
if (content.is(':visible')===true) {
content.hide();
summary.show();
$(linkObj).addClass('closed').removeClass('opened');
$(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
} else {
content.show();
summary.hide();
$(linkObj).removeClass('closed').addClass('opened');
$(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
}
return false;
}
, который в настоящее время доступен каждый раз, когда документация генерируется в файле с именем dynsections.js, помещенном в корень документации.
Что касается этого кода, можно ознакомиться с условиями, позволяющими создавать складываемый код из его / ее собственной документации с использованием Javascript, избегая внутренних сбоев выполнения в этой функции и предотвращая интерпретацию дальнейшего кода javascript.
<Ол>id
src
- summary class
- content example-div
- trigger С учетом этих условий можно создать следующий код.
## <a href="javascript:toggleVisibility($('#example-div'))">Fold me</a>
## <div id="example-div">
## <div id="example-div-summary"></div>
## <div id="example-div-content">
## <pre>
## foo
## bar
## </pre>
## </div>
## <div id="example-div-trigger" src="-"></div>
## </div>
## @htmlonly <script type="text/javascript">$("#example-div").ready(function() { toggleVisibility($("#example-div")); });</script> @endhtmlonly
Приведенный выше код doxygen используется для документирования кода bash с помощью bash-doxygen , поэтому выглядят немного иначе, чем чистый кодекс с кислородом. Первая часть, касающаяся контейнеров div, уже описана с упоминанием условий для соответствия источнику функции <=> и обеспечения ее выполнения без каких-либо ошибок, настраивая комментарии doxygen для наших нужд. Р>
Здесь используется уникальный префикс идентификатора <=>. В первой строке указана гиперссылка для развертывания раздела с использованием javascript напрямую в сочетании с некоторым кодом jQuery . р>
Осталось только один вкладыш в конце. Он содержит jQuery , который необходимо запустить для первоначального сворачивания определенного сегмента. Для bash-doxygen (и, возможно, других языков) блок должен быть однострочным из-за области действия скрипта
Обычно содержимое между \ htmlonly и \ endhtmlonly вставляется как есть. Если вы хотите вставить фрагмент HTML, имеющий область видимости блока, например таблицу или список, который должен находиться за пределами & Lt; p & Gt; .. & Lt; / p & Gt ;, это может привести к неверный HTML. Вы можете использовать \ htmlonly [block], чтобы doxygen завершил текущий абзац и перезапустил его после \ endhtmlonly.
, как отмечено в документации по кислороду и в примечании ниже справа, отмеченном решение ответа от stackoverflow на включая теги сценариев в документацию Doxygen .
Спасибо за чтение. Надеюсь, что это поможет некоторым людям, которые приходят сюда.