Documentation of F´ Projects
Most projects need to generate documentation on the software. F´ uses Doxygen to generate project documentation and projects using F´ may use Doxygen to generate their project documents. Doxygen was chosen because it can run automatically on F´ markdown and C++ documents to generate a web-compatible (HTML) version of the documentation.
The document will describe the basic usage of Doxygen for F´ projects and will also discuss some key settings that projects may wish to change. The output of Doxygen will be a set of HTML files that allow inspection of the project markdowns and C++ code. F´ Doxygen documentation may be viewed to see what the output will look like and is available at https://nasa.github.io/fprime/UsersGuide/api/c++/html/index.html.
Basic Doxygen Usage
Although a full understanding of Doxygen is outside of the scope of this document, we will attempt to discuss the basic usage of doxygen as it pertains to F´. Doxygen requires two things - a working directory and a configuration file. It will recurse through the working directory, generating documentation using the settings set in the configuration.
If the user wishes to include autocoded parts of F´ in the documentation, make sure to build your F´ project before running Doxygen. Make sure to delete or exclude (see EXCLUDE settings below) any non-native builds before running.
The working directory should be the root of the project that is to be documented. A configuration file can be generated
or the sample can be used/modified. To run Doxygen through the GUI, select the working directory and a configuration
file and then run generation. Alternatively, the doxygen command line utility can be run. Change to the working
directory and supply the path to the configuration file. More detail can be found on the
Doxygen website.
A sample configuration file can be seen at https://github.com/nasa/fprime/blob/devel/docs/doxygen/Doxyfile. This file can be used to run documentation of a project. Note: the output directory inside F´ will need to be changed basic configuration settings are described below.
Once generated, load index.html in the output directory using a web browser to view the documentation.
Basic Doxygen Configuration
There are certain settings that users should change in the above configuration sample, and likely these settings should be changed when starting from scratch.
Note: The sample file and templated Doxygen configuration give a detailed explanation of each Doxygen setting.
Key Settings
These settings are essential to use Doxygen to generate documentation.
| Setting | Description | Example |
|---|---|---|
| OUTPUT_DIRECTORY | Directory relative to working directory to write out HTML. | ./docs |
| STRIP_FROM_PATH | Paths to strip out of documentation. Add your project’s build cache to this. | ./MyProject/build-fprime-automatic-native/ |
| STRIP_FROM_INC_PATH | Paths to strip from autocoder include files. Add your project’s build cache to this. | ./MyProject/build-fprime-automatic-native/ |
| USE_MDFILE_AS_MAINPAGE | Set a MD file to be the landing page documentation | MyProject/README.md |
| MARKDOWN_SUPPORT | Pull in markdown files | YES |
| RECURSIVE | Run doxygen recursively | YES |
| EXCLUDE | Paths to exclude. Used to not generate fprime Doxygen inside project documentation. | ./fprime |
| EXCLUDE_PATTERNS | Wildcard patterns to not include | MyProject/test* |
Project Descriptions
There are several settings that describe the basic project - these are listed in the table below: (a project should change these settings)
| Setting | Description |
|---|---|
| PROJECT_NAME | Name of the project displayed prominently in the documentation |
| PROJECT_NUMBER | Project version number |
| PROJECT_BRIEF | Brief description of the project |
| PROJECT_LOGO | 200x50 or smaller logo for the project. Leave blank for no logo |
GitHub Pages Notes
There is a small problem with the Doxygen files being generated and then subsequently hosted on GitHub pages. This is because Doxygen converts the leading / of markdown paths to an _ which then is ignored by Jekyll, a static site generator used by gh-pages.
Possible fixes:
-
Projects can set no-jekyll on their GitHub pages. This will prevent converting MD to web pages, but the HTML output of Doxygen will be hosted as is. This is a good choice for projects that just want to host Doxygen output.
-
Rename underscore files. This is necessary when Jekyll needs to preprocess MD files. A sample renaming script can be found next to the Doxygen sample configuration. Mileage may vary.