Documenting Code

Instructions to build locally documentation and push it to repo.

Setting up documentation

Documentation is built by doxygen in the ./dochtml/html directory. To set it up on you local repo, follow these steps AFTER you have cloned the repo

git push
mkdir dochtml
mkdir dochtml/html
cd dochtml/html
git clone https://github.com/<reponame> .
git checkout gh-pages
# remove other branch(es)
git branch -d master
cd ../..

For initial setup (creating gh-pages branch for the first time)

git push
mkdir dochtml
mkdir dochtml/html
# exclude dochtml from repo
echo "dochtml/" >> .gitignore
git commit -am "added dochtml to gitignore"
cd dochtml/html
git clone https://github.com/<reponame> .
git checkout -b gh-pages
# remove other branch(es)
git branch -d master
# remove files to start from clean state. Change file list as needed
git rm -r src doc config configure.ac LICENSE Makefile.am 
cd ../..

Updating documentation

doxygen

Github documentation

File README.md is the front page for documentation on the github site. It includes a link to ./index.md which is the top menu for the documentation, from which all documentation should be accessible.

Doxygen input files

Documentation is generated by doxygen from multiple sources:

• pages.dox top-level menu, which is the main page for doxygen-generated documentation. Contains entries such as @subpage page_pagename or @ref page_pagename that point to corresponding {#page_installation} tags in any of the doc/xxx.md files.
• markdown files (<filename>.md) in doc/ directories
• documentation contained in source code (.c and .h files)

Other documentation

Additional documentation that is not meant to be processed by doxygen (but can be linked from it) should be placed in directories named docdir. This can consist of pdf files, markdown file, or any other format.

Summary table

File / Directory	Github	Doxygen	Content
README.md	X		top level overview (application specific)
index.md	X		Main help index
pages.dox		X	top doxygen menu (application specific)
./doc/*.md		X	Generic documentation files
./docapp/*.md		X	Application specific docs
./src/doc/*.md		X	Generic documentation files
./src/docdir/*.md			non-doxygen documentation
./src/<modulename>/doc/*.md		X	Module documentation files
./src/<modulename>/docdir/*.md			Extended application documentation

Additional details:

• README.md: file appears on github's front page, and contains an overview description of the software package.
• index.md: top menu for github documentation page. Contains links to help pages in other directories. Standard links include:
  • installation guide, usually in ./doc/ directory
  • user's guide, usually in ./src/<modulename>/doc and ./src/<modulename>/docdir directories
  • programmer's guide generated by doxygen: ./html/index.html