How to generate rdoc-style collapsable code sections?

Question

I am creating internal documentation for a C++ project using Doxygen. I am having Doxygen include the source for methods, etc., but this makes the page kind of hard to scan. I'd like it to behave like rdoc and hide the source in a block that is collapsed by default.

I thought that HTML_DYNAMIC_SECTIONS might let me do this, but alas, the changelog says that option only affects diagrams and graphs.

Maybe I could do it by editing the LAYOUT_FILE?

Anyhow, smart people, how can I coerce Doxygen to generate collapsable code sections?

Answer 1

if includ[ing] the source for methods, etc, [...] makes the page kind of hard to scan, why don't you just link to it (SOURCE_BROWSER = YES) instead of including it (INLINE_SOURCES = YES)? this would make the pages easier to scan and faster to load, and the source would still be accessible (at the expense of one more source page load). depends on how often you actually need to access the source, i guess.

that being said, there is a way to generate collapsible code sections (you will have to modify the source and recompile Doxygen, though):

• collapsible sections in Doxygen's HTML output are marked with two nested <div>s like so:

    <div class="dynheader"><div class="dynsection">
    [collapsible section]
    </div></div>

• included code sections are marked like so: <div class="fragment"><pre class="fragment">...</pre></div>

• thus, to make the included code sections collapsible, you have to either

  • modify the code that generates the <div class="fragment"><pre class="fragment">...</pre></div> to generate <div class="dynheader"><div class="dynsection">...</div></div> (and probably adjust some css), or
  • change the javascript initDynSections() function that scans and collapses the collapsible sections to recognize <div class="fragment"><pre class="fragment"> as one of them.

the implementation (or going the SOURCE_BROWSER route :)) is left as an exercise for the reader. good luck!

oh, and if you should succeed with a patch, it would be great if you could submit it to dimitri so that he can include it in a future version. thanks!

Answer 2

coming along here using the search engine of my choice i just want to leave a note here that it is not absolutely necessary to modify any doxygen source.

When this question was asked there was probably no possibility to embed pure html using the htmlonly tag but with this in mind one is able to create foldable container sections abusing a function named 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;
 }

that is currently available every time the documentation is generated in a file called dynsections.js placed in the documentation root.

Regarding this code one gets to know the conditions to be able to create foldable code from his/her own documentation using Javascript avoiding inner execution faults in this function and preventing further javascript code from being uninterpreted.

1. dom element with a unique identifier id
2. another encapsulated dom element with unique identifier id-summary
3. another encapsulated dom element with unique identifier id-content
4. another encapsulated dom element with unique identifier id-trigger
5. the id-trigger element must contain a src attribute with at least 1 character
6. the class attributes of the main containers do not matter

With theese conditions in mind one can create the following 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
##     </pre>
##   </div>
##   <div id="example-div-trigger" src="-"></div>
## </div>
## @htmlonly <script type="text/javascript">$("#example-div").ready(function() { toggleVisibility($("#example-div")); });</script> @endhtmlonly

The doxygen code above is used to document bash code using bash-doxygen so it might look a bit different from pure doxygen code. The first part involving the div containers is already described mentioning the conditions to fit the source of the function toggleVisibility and make it executable without any errors adjusting the doxygen comments for our needs.

The unique id prefix used in here is example-div. In line one there is a hyperref link setup to unfold a section using javascript directly in conjunction with some jQuery code.

What's left is the one liner at the end. It contains the jQuery script need to be run to initially fold the specific segment. For the bash-doxygen (and probably other languages) the block needs to be a one liner because of the script's block scope

Normally the contents between \htmlonly and \endhtmlonly is inserted as-is. When you want to insert a HTML fragment that has block scope like a table or list which should appear outside <p>..</p>, this can lead to invalid HTML. You can use \htmlonly[block] to make doxygen end the current paragraph and restart it after \endhtmlonly.

as noticed in the doxygen documentation and a comment below the right marked solution of the stackoverflow answer on including script tags in doxygen documentations.

Thank you for reading. Hope this helps some people that come along here.