Comment générer des sections de code réductibles de style rdoc?
-
05-07-2019 - |
Question
Je crée une documentation interne pour un projet C ++ utilisant Doxygen. Doxygen inclut le code source des méthodes, etc., mais cela rend la page difficile à analyser. J'aimerais qu'il se comporte comme un rdoc et masque la source dans un bloc réduit par défaut.
Je pensais que HTML_DYNAMIC_SECTIONS
pourrait me permettre de le faire, mais hélas, le journal des modifications indique que cette option ne concerne que les diagrammes et les graphiques.
Peut-être que je pourrais le faire en modifiant le LAYOUT_FILE
?
Quoi qu'il en soit, personnes intelligentes, comment puis-je contraindre Doxygen à générer des sections de code réductibles?
La solution
si inclut la source pour les méthodes, etc., [...] rend la page difficile à analyser , pourquoi ne pas simplement lier lui ( SOURCE_BROWSER = YES
) au lieu de , y compris il ( INLINE_SOURCES = YES
)? cela rendrait les pages plus faciles à numériser et à charger plus rapidement, et la source serait toujours accessible (au détriment d'un chargement de page source supplémentaire). dépend de la fréquence à laquelle vous avez réellement besoin d'accéder à la source, je suppose.
Cela étant dit, il y a un moyen de générer des sections de code réductibles (vous devrez cependant modifier le source et recompiler Doxygen):
- sections réductibles dans la sortie HTML de Doxygen sont marqués avec deux
<div>
s imbriqués comme suit:
<div class="dynheader"><div class="dynsection">
[collapsible section]
</div></div>
- les sections de code incluses sont marquées comme suit:
<div class="fragment"><pre class="fragment">...</pre></div>
-
donc, pour rendre les sections de code incluses réductibles, vous devez soit
- modifier le code qui génère le
<div class="dynheader"><div class="dynsection">...</div></div>
pour générerinitDynSections()
(et probablement ajuster certains css), ou - changez le javascript
<div class="fragment"><pre class="fragment">
fonction qui analyse et réduit les sections réductibles pour reconnaîtreSOURCE_BROWSER
comme étant l'une d'entre elles.
- modifier le code qui génère le
l'implémentation (ou la <=> route :)) est laissée comme un exercice pour le lecteur. bonne chance!
Oh, et si vous réussissiez avec un correctif, ce serait génial si vous pouviez soumettez-le à dimitri afin qu’il puisse l’inclure dans une future version. merci!
Autres conseils
venant ici en utilisant le moteur de recherche de mon choix, je veux juste laisser ici une note indiquant qu'il n'est absolument pas nécessaire de modifier une source de doxygen.
Lorsque cette question a été posée, il était probablement impossible de incorporer du code HTML pur à l'aide de la balise htmlonly
mais en gardant cela à l'esprit, il est possible de créer des sections de conteneur pliables utilisant une fonction nommée 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;
}
disponible à chaque fois que la documentation est générée dans un fichier nommé dynsections.js placé à la racine de la documentation.
En ce qui concerne ce code, il faut connaître les conditions pour pouvoir créer du code pliable à partir de sa propre documentation en utilisant Javascript, évitant ainsi les erreurs d’exécution interne de cette fonction et empêchant la poursuite du code javascript.
- élément dom avec un identifiant unique
id
- un autre élément dom encapsulé avec un identifiant unique
src
- summary - un autre élément dom encapsulé avec un identifiant unique
class
- content - un autre élément dom encapsulé avec un identifiant unique
example-div
- trigger - l'élément <=> - trigger doit contenir un attribut <=> d'au moins 1 caractère
- les <=> attributs des principaux conteneurs n'ont pas d'importance
En gardant ces conditions à l’esprit, vous pouvez créer le code suivant.
## <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
Le code doxygen ci-dessus est utilisé pour documenter le code bash à l'aide de bash-doxygen . semble un peu différent du code pur doxygen. La première partie concernant les conteneurs div est déjà décrite et mentionne les conditions pour adapter la source de la fonction <=> et la rendre exécutable sans erreur en adaptant les commentaires doxygen à nos besoins.
Le préfixe d'identifiant unique utilisé ici est <=>. La ligne 1 contient un lien hyperref permettant de déplier une section utilisant javascript directement avec du code jQuery .
Ce qui reste est la doublure à la fin. Il contient le script jQuery qui doit être exécuté pour plier initialement le segment spécifique. Pour le bash-doxygen (et probablement d’autres langages), le bloc doit être constitué d’une ligne, en raison de la portée du bloc du script
Normalement, le contenu entre \ htmlonly et \ endhtmlonly est inséré tel quel. Lorsque vous souhaitez insérer un fragment HTML dont la portée de bloc, telle qu'une table ou une liste, doit apparaître à l'extérieur de & Lt; p & Gt; .. & Lt; / p & Gt ;, cela peut entraîner invalider le HTML. Vous pouvez utiliser \ htmlonly [block] pour que doxygen termine le paragraphe actuel et le redémarre après \ endhtmlonly.
comme indiqué dans la documentation sur doxygen et un commentaire en bas à droite marqué solution de la réponse stackoverflow sur inclure des balises de script dans les documentations doxygen .
Merci d'avoir lu. J'espère que cela aidera certaines personnes qui viennent ici.