Come generare sezioni di codice comprimibili in stile rdoc?
-
05-07-2019 - |
Domanda
Sto creando la documentazione interna per un progetto C ++ usando Doxygen. Sto Doxygen include la fonte per i metodi, ecc., Ma questo rende il tipo di pagina difficile da scansionare. Mi piacerebbe che si comportasse come rdoc e nascondesse la fonte in un blocco che è compresso di default.
Ho pensato che HTML_DYNAMIC_SECTIONS
potrei lasciarmi fare questo, ma purtroppo il log delle modifiche dice che l'opzione influenza solo diagrammi e grafici.
Forse potrei farlo modificando LAYOUT_FILE
?
Comunque, gente intelligente, come posso forzare Doxygen a generare sezioni di codice comprimibili?
Soluzione
se include [ing] la fonte di metodi, ecc., [...] rende il tipo di pagina difficile da scansionare , perché non basta link ( SOURCE_BROWSER = YES
) anziché incluso it ( INLINE_SOURCES = YES
)? questo renderebbe le pagine più facili da scansionare e più veloci da caricare, e la fonte sarebbe comunque accessibile (a spese di un altro caricamento della pagina di origine). dipende da quanto spesso devi effettivamente accedere alla fonte, immagino.
detto questo, è un modo per generare sezioni di codice comprimibili (dovrete comunque modificare il sorgente e ricompilare Doxygen):
- sezioni comprimibili nell'output HTML di Doxygen sono contrassegnati con due
<div>
s nidificati in questo modo:
<div class="dynheader"><div class="dynsection">
[collapsible section]
</div></div>
- le sezioni di codice incluse sono contrassegnate in questo modo:
<div class="fragment"><pre class="fragment">...</pre></div>
-
quindi, per rendere comprimibili le sezioni di codice incluse, è necessario
- modifica il codice che genera il
<div class="dynheader"><div class="dynsection">...</div></div>
per generareinitDynSections()
(e probabilmente adattare alcuni css), oppure - modifica la javascript
<div class="fragment"><pre class="fragment">
funzione che analizza e comprime le sezioni comprimibili per riconoscereSOURCE_BROWSER
come una di esse.
- modifica il codice che genera il
l'implementazione (o andando sulla <=> rotta :)) viene lasciata come esercizio per il lettore. buona fortuna!
oh, e se dovessi riuscire con una patch, sarebbe fantastico se tu potessi invialo a dimitri in modo che possa includerlo in una versione futura. grazie!
Altri suggerimenti
venendo qui usando il motore di ricerca di mia scelta, voglio solo lasciare una nota qui che non è assolutamente necessario modificare alcuna fonte doxygen.
Quando è stata posta questa domanda, probabilmente non era possibile incorpora HTML puro usando il tag htmlonly
ma con questo in mente si è in grado di creare sezioni di contenitori pieghevoli abusando di una funzione chiamata 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;
}
che è attualmente disponibile ogni volta che la documentazione viene generata in un file chiamato dynsections.js collocato nella radice della documentazione.
Per quanto riguarda questo codice, si conoscono le condizioni per essere in grado di creare codice pieghevole dalla propria documentazione utilizzando Javascript, evitando errori di esecuzione interni in questa funzione e impedendo l'interpretazione di ulteriori codici javascript.
- elemento dom con un identificativo univoco
id
- un altro elemento dom incapsulato con identificativo univoco
src
- riepilogo - un altro elemento dom incapsulato con identificativo univoco
class
- contenuto - un altro elemento dom incapsulato con identificativo univoco
example-div
- trigger - <=> - l'elemento trigger deve contenere un <=> attributo con almeno 1 carattere
- gli <=> attributi dei contenitori principali non contano
Tenendo presenti queste condizioni, è possibile creare il seguente codice.
## <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
Il codice doxygen sopra è usato per documentare il codice bash usando bash-doxygen , quindi potrebbe sembra un po 'diverso dal codice doxygen puro. La prima parte che riguarda i contenitori div è già stata descritta menzionando le condizioni per adattarsi alla sorgente della funzione <=> e renderla eseguibile senza errori che regolano i commenti doxygen per le nostre esigenze.
Il prefisso ID univoco utilizzato qui è <=>. Nella riga uno c'è un'impostazione del collegamento hyperref per aprire una sezione usando javascript direttamente insieme ad un codice jQuery .
Ciò che rimane è l'unico liner alla fine. Contiene lo script jQuery per eseguire inizialmente il fold del segmento specifico. Per bash-doxygen (e probabilmente altre lingue), il blocco deve essere un solo strato a causa dell'ambito del blocco dello script
Normalmente il contenuto tra \ htmlonly e \ endhtmlonly viene inserito così com'è. Quando si desidera inserire un frammento HTML che ha un ambito di blocco come una tabella o un elenco che dovrebbe apparire al di fuori di & Lt; p & Gt; .. & Lt; / p & Gt ;, questo può portare HTML non valido. Puoi usare \ htmlonly [blocco] per fare in modo che doxygen termini il paragrafo corrente e lo riavvii dopo \ endhtmlonly.
come notato nella documentazione doxygen e un commento sotto la destra contrassegnato soluzione della stackoverflow risposta su compresi i tag di script nelle documentazioni di doxygen .
Grazie per aver letto. Spero che questo aiuti alcune persone che vengono qui.