Visão Geral
O código fonte do FreeCAD está comentado para permitir gerar documentação automática sobre programação usando o Doxygen, um popular sistema de criação de documentação de código fonte. O Doxygen consegue documentar tanto o código C++ como Python do FreeCAD, gerando páginas HTML com hyperlinks a cada 'function' e 'class' documentadas.
A documentação está alojada online no FreeCAD API website. Atenção, note que está documentação pode não estar sempre actualizada; se precisar de mais detalhes, faça o download da última versão do código-fonte do FreeCAD e compile a documentação você mesmo. Se tiver questões prementes sobre o código-fonte por favor pergunte na secção de desenvolvimento no FreeCAD forum.
A compilação da documentação da API segue os mesmos passos gerais que a compilação do executável FreeCAD, conforme indicado na página Compilar no Linux.
Fluxo de trabalho geral para compilar a documentação de programação do FreeCAD. Os pacotes Doxygen e Graphviz devem estar no sistema, além do próprio código-fonte do FreeCAD. O CMake configura o sistema para que, com uma única instrução make, a documentação de todo o projeto seja compilada em muitos arquivos HTML com diagramas.
Compilar documentação do código-fonte
Documentação completa
Se tiver o Doxygen instalado, é muito fácil construir a documentação. Instale também o Graphviz para ser capaz de produzir diagramas que mostram as relações entre diferentes classes e bibliotecas no código FreeCAD. O Graphviz também é usado pelo gráfico de dependências do FreeCAD para mostrar as relações entre diferentes objetos.
sudo apt install doxygen graphviz
Em seguida, siga os mesmos passos que você faria para compilar o FreeCAD, conforme descrito na página de compilação no Linux, e resumido aqui por conveniência.
- Obtenha o código fonte do FreeCAD e coloque-o no seu próprio diretório
freecad-source. - Crie outro diretório
freecad-buildno qual você compilará o FreeCAD e a sua documentação. - Configure os códigos-fonte com o
cmake, certificando-se de indicar o diretório de origem e especifique as opções necessárias para a sua compilação. - Acione a criação da documentação usando o
make.
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
mkdir freecad-build
cd freecad-build
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ../freecad-source
Enquanto estiver dentro do diretório de compilação, emita a instrução a seguir para criar somente a documentação.
make -j$(nproc --ignore=2) DevDoc
Como mencionado em compilar (mais rápido), a opção -j define o número de núcleos CPU usados na compilação. Os ficheiros de documentação resultantes irão aparecer no directório.
freecad-build/doc/SourceDocu/html/
O ponto de entrada para a documentação é o arquivo index.html, que você pode abrir com um navegador da web:
xdg-open freecad-build/doc/SourceDocu/html/index.html
O alvo DevDoc irá gerar uma quantidade significativa de dados, cerca de 5 GB de novos arquivos, particularmente devido aos diagramas criados pelo Graphviz.
Documentação reduzida
A documentação completa usa cerca de 3Gb de espaço em disco. Uma versão alternativa e menor da documentação, que ocupa apenas cerca de 600 MB, pode ser gerada com um destino diferente. Esta é a versão exibida no site da API FreeCAD.
make -j$(nproc --ignore=2) WebDoc
A documentação no FreeCAD API website é gerada automaticamente a partir do https://github.com/FreeCAD/SourceDoc. Qualquer pessoa a pode reconstruir e requerer um pedido de atualização:
- Ramificação do repositório em https://github.com/FreeCAD/SourceDoc
- No seu PC: clone o código FreeCAD (se ainda não tiver feito), crie um directório de compilação para o doc e clone o repositório SourceDoc acima. Esse SourceDoc será atualizado quando você recriar o documento, e poderá confirmar & atualizar os resultados em seguida:
git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push
- Aceda à sua cópia do repositório online e crie uma solicitação de 'pull'.
Outras versões
FreeCAD 0.19 development documentação criada por qingfeng.xia.
Integrar documentação do Coin3D
Em sistemas Unix é possível vincular a documentação de origem do Coin3D com o FreeCAD's. Isso permite uma navegação mais fácil e diagramas de herança completos para classes derivadas de Coin.
- Instale o
libcoin-doc,libcoin80-doc, ou pacote com nome semelhante. - Descompacte o arquivo
coin.tar.gzlocalizado em/usr/share/doc/libcoin-doc/html; Os arquivos podem já estar descompactados no seu sistema. - Gere novamente a documentação de origem.
Se não instalar o pacote de documentação para Coin, os links serão gerados para aceder à documentação online no BitBucket. Isso acontecerá se um tag file Doxygen puder ser baixado no momento da configuração com o wget.
Usando o Doxygen
Consulte a página Doxygen para obter uma explicação extensa sobre como comentar o código-fonte C++ e Python para que ele possa ser processado pelo Doxygen para criar automaticamente a documentação.
Essencialmente, um bloco de comentários começando com /** ou /// para C++, ou ## para Python, precisa aparecer antes de cada definição de classe ou função, para que seja captado pelo Doxygen. Muitos comandos especiais, que começam com \ ou @, podem ser usados para definir partes do código e formatar a saída. A sintaxe de Markdown também é entendida dentro do bloco de comentários, o que torna conveniente para enfatizar certas partes da documentação.
/**
* Returns the name of the workbench object.
*/
std::string name() const;
/**
* Set the name to the workbench object.
*/
void setName(const std::string&);
/// remove the added TaskWatcher
void removeTaskWatcher(void);
Esta página foi obtida de https://wiki.freecad.org/Source_documentation