Как создать разборные разделы кода в стиле rdoc?

Question

Я создаю внутреннюю документацию для проекта C++, используя Doxygen.Я включаю в Doxygen исходный код методов и т. д., но из-за этого страницу сложно сканировать.Я бы хотел, чтобы он вел себя как rdoc и скрывал источник в блоке, который по умолчанию свернут.

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

Возможно, я мог бы сделать это, отредактировав LAYOUT_FILE?

В любом случае, умные люди, как мне заставить Doxygen генерировать свертываемые разделы кода?

Answer 1

если включение источника методов и т. д. [...] затрудняет сканирование страницы, почему бы тебе просто связь к этому (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 Маршрут :)) оставлен в качестве упражнения для читателя.удачи!

ох, и если у тебя получится с патчем, было бы здорово, если бы ты смог представить это Дмитрию, чтобы он мог включить его в будущую версию.Спасибо!

Answer 2

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

Когда был задан этот вопрос, у встроить чистый 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.

<Ол>

элемент dom с уникальным идентификатором id

еще один инкапсулированный элемент dom с уникальным идентификатором src - summary

другой инкапсулированный элемент dom с уникальным идентификатором class - content

другой инкапсулированный элемент dom с уникальным идентификатором example-div - trigger

триггерный элемент <=> - должен содержать атрибут <=>, содержащий не менее 1 символа

атрибуты <=> основных контейнеров не имеют значения

С учетом этих условий можно создать следующий код.

## <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 .

Спасибо за чтение. Надеюсь, что это поможет некоторым людям, которые приходят сюда.