Links para partes anteriores:
- Parte um - introdução, primitivas gráficas necessárias para criar uma representação gráfica do código
- Parte dois - implementação de uma representação gráfica do gerador de código (feito principalmente em Python), linguagem de micro marcação
- Parte Três - Novos Recursos Gráficos
Um exemplo de ambiente que suporta essa representação gráfica é mostrado na imagem abaixo.
Ambiente de suporte a código gráficoA quarta parte do artigo se concentrará em apoiar o processo de documentação.
Ao redor do mato
Vamos ver o que está disponível para o desenvolvedor em termos de trabalho com a documentação.
O Python suporta linhas de documentação para módulos, classes e funções. Isso é bom Às vezes, os comentários também são usados para documentação.
Existem geradores de documentação como
doxygen e
sphinx . Isso também é bom.
No entanto, às vezes você quer um pouco mais. Há momentos em que a descrição de uma função ou classe fica muito grande e as linhas de documentação (ou comentários) desnecessariamente "aumentam". O número de linhas não executáveis começa a suprimir o número de linhas executáveis, o que pode dificultar a leitura devido ao código embaçado. Outro problema são os vários gráficos. Você não pode inserir uma imagem finalizada no texto. É possível inserir apenas uma descrição do diagrama, por exemplo, um diagrama
UML da planta , mas mesmo nesse caso é necessário fornecer renderização, o que é difícil de executar diretamente no texto do programa.
A solução para o problema é simples - salvar uma descrição extensa em um arquivo separado e deixar uma anotação no código que indica a documentação. Um único arquivo pode ser renderizado adequadamente no momento certo. E a marca no código deve ser preferencialmente interativa, ou seja, fornecer uma transição para a documentação com um clique do mouse. Em princípio, a marcação no texto do programa pode ser considerada de forma mais ampla: pode ser uma URL e algum lugar em outro arquivo do texto de origem, uma imagem e um arquivo externo com documentação.
É fácil imaginar um backlink. Digamos que a documentação mencione uma classe do código fonte de um programa ou mesmo de um bloco específico de código. Nesse caso, também seria bom fornecer uma transição rápida para o trecho de código desejado.
Precisamos considerar outro cenário importante. Suponha que durante o desenvolvimento houvesse um desejo de criar um arquivo de documentação externo. É altamente desejável que a questão organizacional - onde armazenar, como chamar, como colocar um link para a documentação - seja resolvida o mais automaticamente possível, para que não haja barreira desnecessária que possa sufocar o impulso justo de criar documentação.
Uma discussão separada merece a questão do formato dos arquivos de documentação. Recentemente, a
redução ganhou
popularidade , apesar das críticas (por exemplo,
aqui ). Digamos que o github mostre automaticamente a documentação de descontos quando você entra na página do projeto, o que é bastante conveniente. Nesse caso, você precisa seguir um acordo muito simples e intuitivo sobre a nomeação e o local do arquivo. As ferramentas para trabalhar com remarcações também são abundantes, portanto esse formato é um bom candidato.
Implementação no Codimension IDE
Juntamente com o texto, o
Codimension IDE oferece suporte à representação gráfica de código. O IDE também suporta linguagem de marcação. Portanto, a tarefa de adicionar um novo elemento gráfico para exibir links para a documentação é bastante simples.
Para começar, formulamos os requisitos para novas funcionalidades de forma compacta:
- Suporte ao formato de remarcação com renderização on-the-fly (visualizar e editar)
- Na representação gráfica do código, suporte um novo elemento para documentação usando a linguagem de marcação CML
- O elemento gráfico da documentação deve funcionar em três versões: apenas um link para outro local; ancorar apenas para links de outros lugares; e link e âncora
- O link pode ser um URL ou apontar para um arquivo (possivelmente com um número de linha ou âncora) que o IDE possa exibir
- No suporte de descontos , diagramas UML da planta
- Suporte a criação rápida de novos arquivos de documentação e links para eles para apresentação gráfica de código
- Mantenha o ponto de partida da documentação da documentação de um projeto, semelhante a como o github faz
Remarcação e renderização
O Codimension IDE usa o
qutepart como um componente do editor de texto, e o qutepart, por sua vez, oferece suporte à
marcação imediata: o realce da sintaxe já foi realizado. Para renderização automática, você pode usar a mesma abordagem que para arquivos python. O campo principal é dividido em duas partes. À esquerda está o texto de remarcação e à direita está renderizando:
Editando remarcação com renderização automáticaA renderização, é claro, é feita automaticamente. O IDE define uma pausa na edição de texto e atualiza a renderização, se necessário. Para a exibição de remarcação, o lado esquerdo com um editor de texto é suprimido.
Era conveniente usar a biblioteca
Mistune para
renderização , o que permite converter rapidamente texto em HTML. O HTML pronto é enviado ao componente QT para exibição. A biblioteca Mistune também se mostrou flexível o suficiente para agregar reconhecimento às descrições dos diagramas plantUML. O diagrama é adicionado como um bloco de código com o idioma correspondente, por exemplo:
Reconhecimento do diagrama PlantUMLO plantUML suporta vários tipos de diagramas. Para
Codimension, a descrição do diagrama é transparente, ou seja, não é analisada, mas o plantUML é transmitido como é. Assim, todos os tipos suportados serão exibidos na janela de exibição. No momento da redação deste artigo, o plantUML suportava as seguintes tags de início / fim para vários tipos de diagramas:
- @startuml / @enduml
- @startgantt / @endgantt
- @startsalt / @endsalt
- @startmindmap / @endmindmap
- @startwbs / @endwbs
- @startditaa / @endditaa
- @startjcckit / @endjcckit
O arquivo de marcação editável pode conter vários diagramas, além de imagens baixadas da rede. Uma situação frequente é quando muito pouco texto é alterado e os recursos gráficos permanecem inalterados. Para não gerar a mesma coisa todas as vezes e não regenerar diagramas, era necessário implementar um cache de recursos semelhantes.
Na biblioteca QT, o componente QTextBrowser que suporta HTML é usado. Infelizmente, o dialeto suportado do HTML é limitado, portanto, o resultado final é quase impossível de aperfeiçoar. Talvez esse defeito possa ser corrigido no futuro.
Também foi necessária intervenção pelo processamento de cliques do mouse nos links. Alguns dos seguintes itens podem aparecer no link:
- recurso externo (começa com http: // ou com https: //)
- um arquivo com um caminho relativo da raiz do projeto ou do arquivo atual (conveniente quando o diretório do projeto é movido pelo sistema de arquivos)
- caminho absoluto do arquivo c
E se for um arquivo, você poderá especificar (elemento opcional) o identificador da âncora nesse arquivo ou o número da linha. Nos dois casos, informações adicionais são usadas para rolar o arquivo para o local desejado.
Elemento gráfico
Faz sentido inserir um elemento gráfico usando um novo comentário CML, semelhante ao que já foi feito, por exemplo, para grupos. A CML suporta atributos, que também são necessários para o novo elemento gráfico.
Um link para a documentação é, de certa forma, semelhante a um comentário - não é uma linha executável do programa, mas fornece informações adicionais sobre algum contexto.
O IDE do Codimension reconhece vários tipos de comentários: independente, principal e lateral. Para a documentação, parece prudente manter elementos gráficos independentes e principais da mesma maneira que nos comentários. Há confusão com o elemento lateral para documentação. O ponto é como os comentários secundários são renderizados para um bloco de código de várias linhas. Um retângulo é desenhado à direita do bloco, cobrindo todas as linhas do comentário lateral com suporte para números de linhas correspondentes. E o que fazer se o documento da CML encontrado no meio do comentário lateral não estiver totalmente claro. Por outro lado, o link ainda leva a outro lugar; portanto, o suporte para documentos CML laterais parece redundante - o contexto de uma linha específica no bloco de código é muito estreito. O suporte para documentos CML secundários para funções e classes também parece redundante. Portanto, neste estágio, apenas documentos CML independentes e principais serão implementados. Vale ressaltar que, se no futuro houver uma necessidade razoável de oferecer suporte a documentos CML laterais e uma boa idéia de como exibi-los, essa funcionalidade poderá ser adicionada.
Vamos discutir o que precisa ser mostrado em um elemento gráfico. Obviamente, você precisa de texto para o elemento. O texto é definido pelo desenvolvedor e informa a você o que o link aponta. Foi mencionado anteriormente que é desejável fornecer uma transição para a documentação com um único clique. O texto do elemento gráfico não é adequado, porque a continuidade entre o comportamento de outros elementos deve ser respeitada - clicando com o mouse, o elemento gráfico é selecionado. No entanto, resolver o problema é simples: você pode adicionar um ícone, por exemplo, à esquerda do texto e clicar no ícone levará à transição.
Agora a lista de atributos para o comentário do documento CML é clara:
- link - link para outro local
- anchor - identificador de âncora para links de outros lugares
- title - texto a ser exibido no elemento gráfico
- bg, fg, border - cores individuais do elemento, se precisar ser destacado de uma maneira especial
Pelo menos um dos dois atributos link e anchor deve estar presente. Sem eles, esse comentário de documento da CML não faz muito sentido. Outros atributos são opcionais. O texto pode não ser de todo e as cores podem ser padrão.
Aqui está um exemplo de código usando o documento CML e sua representação gráfica:
Comentários independentes e principais sobre documentos da CMLA diferença entre elementos principais e independentes é apenas onde o conector leva: a um bloco específico ou a um conector entre os blocos.
Quando o cursor do mouse está sobre o ícone e o elemento possui um atributo de link, a forma do cursor muda, sugerindo que um clique será executado.
O elemento gráfico também suporta o menu de contexto. Está disponível uma opção para visualizar ou editar atributos do elemento, incluindo cores, e a opção para excluir um elemento.
Outros elementos gráficos
Quase todos os outros elementos na representação gráfica do código podem ter documentação (exceções, por exemplo, são comentários e doutrinas). Portanto, eles têm uma maneira de criar um item de documentação através do menu de contexto.
Menu de contexto para trabalhar com documentaçãoExistem apenas duas opções. O primeiro "Adicionar / editar link / âncora do documento ..." leva a um diálogo modal para inserir manualmente os atributos de link, âncora e título. Aqui, o desenvolvedor tem total liberdade para onde enviar o link, para onde colocar o arquivo etc.
A segunda opção é mais interessante. O nome do item é longo, devido às ações executadas: "Crie um arquivo doc, adicione um link e abra para edição". Todas as ações são executadas automaticamente sem nenhuma entrada, o que permite resolver o problema organizacional rapidamente:
- É tomada uma decisão sobre o arquivo no qual a documentação será localizada (consideraremos abaixo)
- No texto de origem, adicione
# cml 1 doc ... , que aponta para o arquivo de documentação e possui a âncora e o texto gerados. A âncora é gerada como documento <número aleatório>. Texto fixo: Veja a documentação - Se o arquivo de documentação já existir, ele será aberto para edição em uma nova guia
- Se o arquivo de documentação não existir, ele será criado, aberto para edição em uma nova guia e uma breve ajuda será adicionada ao buffer de edição, incluindo como se referir ao novo comentário
# cml 1 doc ... inserido.
A decisão sobre o arquivo depende se o projeto está carregado. Se carregado, o subdiretório doc será criado na raiz do projeto e, em seguida, o caminho relativo da raiz do projeto para o arquivo de texto de origem. O nome do arquivo é formado substituindo a extensão por .md. Por exemplo, se um projeto estiver localizado em
/home/me/myProject
e documentação é adicionada para o arquivo do projeto
/home/me/myProject/src/utils.py
um arquivo de documentação será criado
/home/me/myProject/doc/src/utils.md
Portanto, a estrutura da documentação para o código-fonte repete a estrutura do código-fonte, e mesmo uma rápida olhada no subdiretório doc no projeto será suficiente para uma navegação intuitiva. O esquema parece razoável para o comportamento padrão, o que ajuda a acelerar o trabalho com a documentação.
Se o projeto não for carregado, o subdiretório doc será criado próximo ao arquivo e nele o arquivo com a extensão alterada para .md. Tal cenário, no entanto, parece improvável. Se estamos falando de documentação, é quase certamente um trabalho em um projeto, e não em um arquivo separado.
Obviamente, a qualquer momento, você pode alterar os elementos gerados automaticamente editando
# cml 1 doc ... em um editor de texto ou em uma caixa de diálogo em uma representação gráfica.
Ponto de partida da documentação do projeto
Por que preciso de um ponto inicial de documentação? Na minha opinião, isso pode facilitar o processo de entrada no projeto para aqueles que o abrem pela primeira vez. Por exemplo, no caso de expandir a composição da equipe de desenvolvimento ou para os usuários do projeto. Imagine que o projeto tenha documentação e consiste em um grande número de arquivos. Por onde começar? Como está estruturada a documentação? Em vez de especular e depois verificá-los, seria mais conveniente ter uma indicação explícita do ponto de entrada recomendado.
Aqui você pode estender um pouco a abordagem do github para que as opções padrão e específica da organização da documentação funcionem. Se nada for dito, procuraremos o arquivo README.md na raiz do projeto. E as propriedades do projeto podem ser expandidas com outro campo, o que indica um arquivo específico do ponto de partida da documentação.
Existem duas opções para abrir a documentação do projeto. Um botão com o ícone de descontos foi adicionado à barra de ferramentas da janela principal do IDE. Quando clicado, o arquivo de documentação será aberto no modo de visualização, se disponível. Se não houver arquivo, o local do arquivo de documentação será oferecido e uma nova guia será aberta no modo de edição com o texto - um esboço. A segunda opção é um link para a página de boas-vindas do
Codimension , que é exibida quando não há outra guia aberta. O texto que o acompanha incluirá palavras sobre a documentação do projeto e um link se a documentação for encontrada. É esta página de boas-vindas que o usuário que abriu o projeto pela primeira vez verá.
Teste na prática
A funcionalidade descrita acima foi testada em gatos, ou seja, no projeto do próprio
Codimension IDE . Agora, o pacote de instalação inclui a documentação preparada no formato de remarcação. Esse teste de funcionalidade não pode ser considerado completamente completo, pois a documentação foi preparada para o usuário final e não por código. No entanto, a impressão geral que resultou é bastante aceitável.
Perguntas abertas
Preciso de suporte para elementos secundários de documentos CML? Se sim, então como desenhá-los, por exemplo, para esse caso:
a = 10
Pode-se reconhecer as descrições do diagrama plantUML diretamente nas linhas de documentação. Se esse suporte for feito, como exibir esses diagramas na representação gráfica do código?
Para facilitar a construção dos diagramas plantUML, pode-se adicionar funcionalidade com este cenário:
- O usuário clica com o botão direito do mouse na classe na representação gráfica do código ou em qualquer outra janela (lista de classes de projeto, conteúdo do arquivo estruturado)
- No menu de contexto, seleciona um item para gerar uma descrição da classe no formato plantUML
- A descrição gerada é salva em um buffer de texto.
- O usuário insere o texto no documento de remarcação e modifica-o, se necessário
A vitalidade desse cenário está em questão, embora seja trivial implementá-lo.
Se você tiver alguma idéia, compartilhe-a nos comentários.