Como gerar seções de código collapsable rdoc de estilo?
-
05-07-2019 - |
Pergunta
Estou criando documentação interna para um projeto C ++ usando Doxygen. Estou tendo Doxygen incluir a fonte para os métodos, etc., mas isso faz com que o tipo página difícil de verificar. Eu gostaria que ele se comporte como rdoc e ocultar a fonte em um bloco que é recolhida por padrão.
Eu pensei que HTML_DYNAMIC_SECTIONS
pode me deixar fazer isso, mas, infelizmente, o changelog diz que a opção só afeta diagramas e gráficos.
Talvez eu pudesse fazê-lo editando o LAYOUT_FILE
?
De qualquer forma, pessoas inteligentes, como posso coagir Doxygen para gerar seções de código dobrável?
Solução
se inclu [ndo] a fonte para os métodos, etc., [...] faz o tipo página de difícil verificação , por que você não apenas link para ele ( SOURCE_BROWSER = YES
) em vez de incluindo que ( INLINE_SOURCES = YES
)? isso tornaria as páginas mais fácil para fazer a varredura e mais rápido para carregar, ea fonte ainda seria acessível (à custa de carregamento da página mais uma fonte). depende de quantas vezes você realmente precisa para acesso a fonte, eu acho.
Dito isto, há é uma maneira de gerar seções de código recolhíveis (você terá que modificar a fonte e recompilar Doxygen, embora):
- seções recolhíveis em saída HTML do Doxygen são marcadas com dois
<div>
s aninhados assim:
<div class="dynheader"><div class="dynsection">
[collapsible section]
</div></div>
- seções de código incluídos são marcadas assim:
<div class="fragment"><pre class="fragment">...</pre></div>
-
Assim, para tornar o código incluído seções recolhíveis, você tem que quer
- o código que gera o
<div class="fragment"><pre class="fragment">...</pre></div>
para gerar<div class="dynheader"><div class="dynsection">...</div></div>
(e provavelmente ajustar algumas css), ou - javascript função
initDynSections()
que scans e colapsos as seções recolhíveis para reconhecer<div class="fragment"><pre class="fragment">
como um deles.
- o código que gera o
a implementação (ou ir a rota SOURCE_BROWSER
:)) é deixado como um exercício para o leitor. boa sorte!
Ah, e se você deve ter sucesso com um patch, seria ótimo se você pudesse submetê-lo para dimitri para que ele possa incluí-lo em uma versão futura. obrigado!
Outras dicas
bem vinda aqui, usando o motor de busca da minha escolha eu só quero deixar uma nota aqui que não é absolutamente necessário para modificar qualquer fonte doxygen.
Quando essa pergunta foi feita provavelmente não havia possibilidade de incorporar html puro usando a tag htmlonly
mas com isso em mente um é capaz de criar seções de contêineres dobráveis ??abusando de uma função chamada 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;
}
que está atualmente disponível cada vez que a documentação é gerada em um arquivo chamado dynsections.js colocados na raiz documentação.
No que se refere este código começa a conhecer as condições para ser capaz de criar um código dobrável de seu / sua própria documentação usando Javascript evitando as faltas de execução internas nesta função e evitar mais código javascript de ser uninterpreted.
- elemento DOM com um
id
identificador único - outro elemento dom encapsulado com identificador exclusivo
id
-resumo - outro elemento dom encapsulado com identificador exclusivo
id
-content - outro elemento dom encapsulado com identificador exclusivo
id
-trigger - o elemento
id
-trigger deve conter um atributosrc
com pelo menos 1 caractere - atribui a
class
dos principais recipientes não importa ??li>
Com as condições theese em mente pode-se criar o código a seguir.
## <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
O código doxygen acima é usado para o código do bash documento usando bash-doxygen para que ele possa olhar um pouco diferente a partir do código doxygen puro. A primeira parte envolvendo os recipientes div já está descrito mencionar as condições para se ajustar a fonte da toggleVisibility
função e torná-lo executável sem quaisquer erros ajustando os comentários doxygen para as nossas necessidades.
O prefixo id único usado aqui é example-div
. Em uma linha existe uma configuração de ligação hyperref para desdobrar uma seção usando javascript diretamente em conjunto com alguns jQuery código.
O que resta é o um forro no final. Ele contém a jQuery necessidade script a ser executado a dobrar, inicialmente, o segmento específico. Para o bash-doxygen (e provavelmente outras línguas) as necessidades bloco a ser um um forro por causa do escopo de bloco do script
Normalmente, o conteúdo entre \ htmlonly e \ é inserido endhtmlonly como está. Quando você quiser inserir um HTML fragmento que tem escopo de bloco como uma tabela ou lista que deve aparecer fora
..
, isso pode levar a inválidos HTML. Você pode usar \ htmlonly [bloco] para fazer final doxygen o parágrafo atual e reiniciá-lo depois de \ endhtmlonly.
como notado no doxygen documentação e um comentário abaixo o direito marcado solução da resposta stackoverflow sobre incluindo marcas de script em documentações doxygen .
Obrigado por ler. Espero que isso ajude algumas pessoas que vêm junto aqui.