Как создать разделы кода в стиле rdoc? - PullRequest
Новая
       37

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

6 голосов
/ 21 октября 2009

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

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

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

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

Ответы [ 2 ]

4 голосов
/ 24 октября 2009

, если включает [источник] методов и т. Д., [...] затрудняет сканирование страницы , почему бы вам просто не связать с ней (SOURCE_BROWSER = YES) вместо , включая it (INLINE_SOURCES = YES)? это облегчило бы сканирование страниц и быструю загрузку, а источник по-прежнему был бы доступен (за счет еще одной загрузки исходных страниц). я думаю, зависит от того, как часто вам нужен доступ к источнику.

как говорится, - это способ генерирования секций свертываемого кода (однако вам придется изменить исходный код и перекомпилировать Doxygen): 

    <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 маршруту :)) оставлена ​​читателю в качестве упражнения. удачи!

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

2 голосов
/ 24 июня 2015

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

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

  1. элемент dom с уникальным идентификатором id
  2. еще один инкапсулированный элемент dom с уникальным идентификатором id -summary
  3. еще один инкапсулированный элемент dom с уникальным идентификатором id -content
  4. еще один инкапсулированный элемент dom с уникальным идентификатором id -trigger
  5. элемент id -trigger должен содержать атрибут src длиной не менее 1 символа
  6. атрибуты class основных контейнеров не имеют значения

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

<code>## <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
##
## ##
## ## @htmlonly $ ("# example-div"). ready (function () {toggleVisibility ($ ("# example-div"));}); @ endhtmlonly

Код doxygen выше используется для документирования кода bash с использованием bash-doxygen , поэтому он может немного отличаться от кода чистого doxygen. Первая часть, включающая контейнеры div, уже описана с упоминанием условий для соответствия источнику функции toggleVisibility и обеспечения ее выполнения без каких-либо ошибок, настраивая комментарии doxygen для наших нужд.

Здесь используется уникальный префикс идентификатора example-div. В первой строке указана гиперссылка для развертывания раздела с использованием javascript напрямую в сочетании с кодом jQuery .

Осталось только один вкладыш в конце. Он содержит скрипт jQuery , который необходимо запустить для первоначального сворачивания определенного сегмента. Для bash-doxygen (и, возможно, других языков) блок должен быть однострочным из-за объема блока скрипта

Обычно содержимое между \ htmlonly и \ endhtmlonly вставляется как есть. Если вы хотите вставить фрагмент HTML, имеющий область видимости блока, например таблицу или список, который должен находиться за пределами

..

, это может привести к неверному HTML. Вы можете использовать \ htmlonly [block], чтобы doxygen завершил текущий абзац и перезапустил его после \ endhtmlonly.

, как замечено в документации doxygen и комментарии под отмеченным справа решением ответа stackoverflow о включении тегов сценария в документацию doxygen .

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

...