In this course
Doxygen is working like the Javadoc, the JSDoc, or a lot of tools allowing you to write documentation and generate a website from it. Doxygen is covering a lot of languages such as C, C++, C#, Java, PHP, and Python.
- you will learn how to use write
- how to generate documentation with
doxygen, so how to write a
- how to generate GREAT documentation with
doxygen(with a beautiful theme)
- some advice about writing documentation
Starting with Doxygen
Doxygen is working like the Javadoc in Java, if you know what I mean.
- write documentation using a special syntax
- use a command to generates a website
- open a file called
index.htmlin your browser and check it out!
The main idea is writing comments like this one in a
/*! * \file my_file.h * \author your name(s) here * \version 0.0.0 * \date a date (the format is up to you) * \see a type/a class/a file we might need to check along this one * \see ... * \brief some brief description * * This is a long and fully explained description * of this file that can include HTML * such as the "ul" or the "ol" tags for * lists... */
\author, ... are a list of
keywords that will allow
doxygen to give some style to your documentation. They start either with a
\ or a
@ like in
Also before starting, note that you will have to say what you are documenting, before actually starting the documentation. An example would be above, you must use a
\fileto say that you are documenting this file. So you would have to use
\enumbefore documenting an enum etc.
All tags can be found in this great reference sheet (PDF).
Generate your documentation website
You will need a file called
Doxyfile to compile your documentation.
You can create one with default values with
When created, you should check these lines and modify them if wanted
PROJECT_NAME = "...": project name
PROJECT_NUMBER = "...": a version such as
PROJECT_BRIEF = "desc": project description
PROJECT_LOGO = "path": project logo
OUTPUT_DIRECTORY = "path": where the generated website is stored.
OUTPUT_LANGUAGE = "English": documentation language
QUIET = YES: do not show hundreds of messages
WARN_IF_UNDOCUMENTED: show warning of not
WARN_IF_DOC_ERROR: show warning of not
INPUT = path: add a file/folder. Only these may have a documentation generated, unless the file extension is excluded.
INPUT += path: add more files/folders. Each time you want to add one, add this line.
RECURSIVE = YES: recursive search of INPUT folders
EXCLUDE = path: exclude some path
IMAGE_PATH = path: if you do have a folder of images that you use in your documentation.
And here we go for the
HTML specifics options
LAYOUT_FILE = "path": a layout to change documentation layout
HTML_HEADER = ./header.html: add a header,
header.htmlis a file that you created
HTML_FOOTER = ./footer.html: add a footer,
footer.htmlis a file that you created
HTML_EXTRA_STYLESHEET = style.css: add a CSS file
HTML_EXTRA_FILES = file.js: add a JS file
and if you want to enable latex
USE_MATHJAX = TRUE: enable mathjax.js
then you have to use
To generates your documentation. Check your
OUTPUT_DIRECTORY for the index.html that you must open in your browser to look at your HTML documentation.
Make your documentation beautiful
download these files from https://github.com/mosra/m.css
pipare not installed, then install them
pip3 install jinja2 Pygments
# used to become a god # style\doxygen.py DoxyfileCSS # include original file @INCLUDE = Doxyfile # modify some values GENERATE_HTML = NO GENERATE_LATEX = NO GENERATE_XML = YES XML_PROGRAMLISTING = NO XML_NS_MEMB_FILE_SCOPE = YES # If you want to change the navbar # to find a special name such as a_page.html # check the usual output folder then link # # M_LINKS_NAVBAR1 = \ # "<a href=\"a_page.html\">User documentation</a>" \ # "annotated" # M_LINKS_NAVBAR2 = \ # "files" \ # "<a href=\"a_page.html\">Functions</a>" \ # "<a href=\"un_lien">GitHub</a>"
- on Linux
chmod +x style/doxygen.py
- then do
- check your usual output folder for your
Make your documentation great
I think we should think carefully about how to make our documentation. Here is some advice, I hope it helps you find ideas about what would make documentation great.
imports, one line, why are you using them
variables, at their initialization, why do you need it
group some part of your code (all
do not write
@return int, a numberor
@param int a number: in most cases it's useless
- maybe tell us the range of the variable
- some values that may trigger a different behavior
don't copy-paste, use
@seeor whatever, but don't copy-paste.
a "big" description at the beginning of a file, to tells us why you are using this file so that we know if we should read it or not.
\versionunless you really intend to modify them, otherwise, they are not useful
- don't forget non-doxygen documentation, one per line or block is helpful
- show some examples of your function is called, that might help a lot
- create a
README.mdsummarizing some usages might be good