Projeto

Geral

Perfil

Wiki »

Documentação de Códigos

Nota: Contribuição original de João Gerd Zell de Mattos (Outubro 2011)

1. Introdução

A necessidade de documentação do código é evidente para todos os desenvolvedores de software, mas varia em extensão de projeto para projeto. A documentação de um código fonte não deve ficar restrita unicamente ao código. É necessário que seja criada uma documentação mais ampla que possa ser disponibilizada para o usuário final assim como para colaboradores do projeto. Muitas vezes esta tarefa torna-se desgastante uma vez que para o bom entendimento e bom uso do software seja necessário a criação de documentos com fins distintos, como por exemplo, um guia de referencia rápida, um guia para desenvolvedores, uma documentação on-line, etc ...

Buscamos, uma forma de manter a documentação dos softwares desenvolvidos pelo grupo consistentes com o código fonte de forma a elaborar um manual de referência útil. É evidente que as limitações de recursos humanos exigem que a produção da documentação evite sobrecarga de trabalho abordando o problema de uma forma minimalista. Assim, foi necessário a busca de uma ferramenta que pudesse gerar uma documentação dentro do próprio código e que pudesse ser reutilizada para documentos HTML, PDF e principalmente que facilitasse a elaboração de documentos técnicos dentro do próprio INPE.

Com base nisso, foi escolhido o ProTeX, um script perl que extrai a informação do cabeçalho de um código fortran padrão, produzindo um documento em LaTeX. O ProTeX foi desenvolvido no Goddard Space Flight Center por Arlindo da Silva, Will Sawyer, e colaboradores.

Dentre as vantagem do uso desta ferramenta destacam-se:

  • A documentação no código é escrita em formato texto, ou seja, é facilmente reproduzível e legível pelos desenvolvedores;
  • A documentação no código é diretamente compilável, ou seja, a documentação está totalmente contida como comentários de código;
  • A documentação é produzida automaticamente em formato LaTeX e HTML, ou com pelo menos um mínimo de intervenção do usuário.

A seguir é apresentado um breve tutorial baseado na documentação original (veja Sawyer et al., 1997), em que busca-se apresentar as principais funcionalidades deta ferramenta através de exemplos de utilização.

2. ProteX

Os scripts, exemplos de cabeçalhos e o arquivo em pdf e ps produzidos com os exemplos de uso do ProTeX podem ser obtidos em protex.tar.gz

Para instalar o protex, faça o seguinte:

$ tar -xvzf protex.tar.gz

Este comando fará com que sejam instalados os seguintes arquivos no subdiretório protex:

  • README: Arquivo que descreve o conteúdo do arquivo tar.gz;
  • protex: Script Perl (por Arlindo da Silva et al.) que converte os cabeçalhos dos códigos de Fortran 90, entre outros formatos de linguagem de programação, no formato LaTeXe ;
  • f90pdf: Script Perl (por Bob Yantosca) que é um wrapper para o protex. Este script chama o protex e o pdflatex para converter a saida do protex no formato PDF;
  • f90ps: Script Perl (por Bob Yantosca) que é um wrapper para o protex. Este script chama o protex, latex e o dvips para converter a saida do protex no formato PostScript;
  • template_introduction.txt: Modelo para a capa do documento para uso com o script protex. Use este modelo para especificar o título do documento, autoria, filiação e data. Este arquivo deve ser sempre o primeiro arquivo passado para protex.
  • template_includefile.h: Modelo de arquivo include com exemplos de declarações;
  • template_module.F90: Modelo para uso com módulos de Fortran 90.
  • template_routine.F90: Modelo de código de Fortran 90 para um programa fortran padrão ou routina (ou seja, não contido em um modulo).
  • sample.pdf: Exemplo de arquivo de saída em PDF, criado a partir dos arquivos template_includefile.h, template_routine.F90 e template_module.F90;
  • sample.ps: Exemplo de arquivo PostScript, criado a partir dos arquivos template_includefile.h, template_routine.F90 e template_module.F90;

3. Produzindo um arquivo no formato PDF

Para gerar um arquivo PDF, digite:

$ f90pdf [lista de arquivos]

Este comando irá produzir estes arquivos:

  • output.tex: Documentação no formato LaTeX;
  • output.pdf: Documentação no formato PDF.

Você pode optar por mudar o nome destes como achar melhor. O f90pdf é um script que executa os seguintes comandos:

  protex -s -f [list of files] > output.tex
  pdflatex output.tex
  pdflatex output.tex
  pdflatex output.tex   
  rm *.dvi *.aux *.log *.toc

desta forma execute esses comandos na sequencia com os nomes que desejar, ou modifique no script f90pdf para que tenham a saída desejada.

O comando pdflatex é um atalho muito útil. O comando pdflatex substitui as chamadas separadas para latex e dvipdf. Por exemplo, os comandos acima são equivalentes a:

  protex -s -f [list of files] > output.tex
  latex output.tex
  latex output.tex
  latex output.tex
  dvipdf output.tex output.pdf
  rm *.dvi *.aux *.log *.toc

3.1 Notas

  • A opção -s do protex fará com que apenas o cabeçalho dos módulos, sub-rotinas e funções sejam incluidos na produção;
  • A opção -f suprime a impressão da informação de arquivos de código fonte ao lado de cada nome do módulo ou rotina;
  • Ao executar o camando pdflatex 3 vezes garante que o sumário será compilado corretamente no arquivo final;
  • Se o script f90pdf "travar", então provavelmente ocorreu algum erro. Para continuar deve-se digitar r ou para sair x.

4. Produzindo um arquivo no formato PostScript

Para gerar um arquivo PostScript, digite:

$ f90ps [lista de arquivos]

Este comando irá produzir estes arquivos:

  • output.tex: Documentação no formato LaTeX;
  • output.ps: Documentação no formato PostScript.

Você pode optar por mudar o nome destes como achar melhor. O f90pdf é um script que executa os seguintes comandos:

  protex -s -f [list of files] > output.tex
  latex output.tex
  latex output.tex
  latex output.tex   
  dvips output.dvi -o output.ps
  rm *.dvi *.aux *.log *.toc

desta forma execute esses comandos na sequencia com os nomes que desejar, ou modifique no script f90ps para que tenham a saída desejada.

5. Produzindo um documento no formato HTML

Para gerar um arquivo HTML a partir dos códigos f90, digite:

$ protex -s -f [list of files] > output.tex
$ latex2html output.tex

Este comando irá chamar o utilitário latex2html (que vem de instalado por padrão em qualquer distribuição Linux) para analisar o arquivo LaTeX "output.tex" e criar páginas HTML.

5.1 Exemplos de arquivos de saída

Foram criados dois aquivos de exemplo (sample.pdf, sample.ps) a partir de exemplos de códigos fonte fortran 90, estes arquivos estão localizados no diretório protex. Estes arquivos foram criados com os seguintes comandos:

$ f90pdf template_introduction.txt *.h *.F90
$ mv output.pdf sample.pdf

$ f90ps template_introduction.txt *.h *.F90
$ mv output.ps sample.ps

5.2 Criação dos Cabeçalhos para uso com o ProTeX

A capa do documento final pode ser definida utilizando-se o arquivo template_introduction.txt como no exemplo:

!-------------------------------------------------------------------------!
!       Group on Data Assimilation Development - GDAD/CPTEC/INPE          !
!-------------------------------------------------------------------------!
!BOI
! !TITLE: Front page template
! !AUTHORS: Joao Gerd and Carlos Bastarz
! !AFFILIATION: Center for Weather Prediction and Climate Studies
! !DATE: Nov 24, 2010
!EOI
!-------------------------------------------------------------------------!

5.3 Notas

  • BOI e EOI para definir a extenção do cabeçalho. O script protex vai processar somente o texto que estiver entre BOI e EOI;
  • O texto seguido pelos rótulos !TITLE, !AUTHORS, !AFFILIATION e !DATE devem ser colocados na mesma linha;
  • Pode ser também especificado um rótulo adicional !INTRODUCTION após o rótulo !DATE, que vai tornar-se o primeiro tópido no sumário. Isso permite voltar mais tarde e inserir manualmente marcações no LaTeX após a produção do arquivo output.tex.
  • É importante que este arquivo seja o primeiro da lista durante a execução do script que irá gerar a documentação.

Para incluir no documento um arquivo de include com seus blocos ou seus parametros utilize o arquivo template_includefile.h como no exemplo:

!-------------------------------------------------------------------------!
!       Group on Data Assimilation Development - GDAD/CPTEC/INPE          !
!-------------------------------------------------------------------------!
!BOP
!
! !MODULE: GC_SomethingIncludeFile.h
!
! !DESCRIPTION: This include file contains the various parameters that will
!   allow the module and routine to do stuff to various things in various
!   routines in various places.
!\\
!\\
! !PUBLIC TYPES:
!
  TYPE t_GeosChemSomething
     !%%% declare stuff here %%%
  END TYPE t_GeosChemSomething
!
! !PUBLIC MEMBER FUNCTIONS:
! None
!
! !PUBLIC DATA MEMBERS:
!
  INTEGER(ESMF_KIND_I8), PUBLIC, PARAMETER :: myIntParam   ! INTEGER value
  REAL(ESMF_KIND_I8),    PUBLIC, PARAMETER :: myRealParam  ! REAL*8 value
!
! !REVISION HISTORY: 
!  21 Nov 2010 - J.G. de Mattos - Initial Version
!
! !REMARKS:
! Protex is great!
!EOP
!-------------------------------------------------------------------------!

5.4 Utilização do ProTeX nos códigos versionados dentro do RSG

Como já foi visto nas seções anteriores, um documento ProTeX utiliza palavras reservadas que deverão ser inseridas dentro dos blocos de comentário e no cabeçalho de cada unidade de código (programa ou rotina Fortran). O ProTeX realiza uma análise destes documentos procurando pelas palavras reservadas e, ao encontrar, gera um documento compatível com o LaTeX. Algumas das palavras reservadas utilizadas pelo ProTeX estão listadas na tabela a seguir.

5.5 Lista das principais Palavras reservadas disponíveis no ProTeX

Palavra Reservada Descrição
!BOP ou !BOI Início de uma seção ProTeX
!EOP ou !EOI Fim de uma seção ProTeX
!MODULE: Nome do Módulo
!DESCRIPTION: Descrição do Módulo/Rotina
!REVISION HISTORY: Informações sobre o Autor e a Revisão
!INTERFACE: Declaração do estado do Módulo/Rotina
!USES: Indica quais módulos são utilizados
!ROUTINE: Nome da Rotina/Função
!INPUT/OUTPUT PARAMETERS: Declaração de Input/Output

protex.tar.gz (99,4 KB) Bastarz, Carlos Frederico, 27 Setembro 2022 15:52