Next: , Previous: Code Fixing, Up: Tools


13.4 Documentation Generation

GPS provides a documentation generator which processes source files and generates annotated HTML files.

Note that starting with GPS 4.2, a brand new Documentation generator has been put in place. This new generator is much faster than the previous one, and produces cleaner and clearer html files.

It is based on the source cross-reference information (e.g. generated by GNAT for Ada files). This means that you should ensure that cross-reference information has been generated before generating the documentation. It also relies on standard comments that it extracts from the source code. Note that unlike other similar tools, no macro needs to be put in your comments. The engine in charge of extracting them coupled with the cross-reference engine gives GPS all the flexibility needed to generate accurate documentation.

The documentation is put into a directory called doc, created under the object directory of the root project loaded in GPS.

Once the documentation is generated, the main documentation file is loaded in your default browser.

The documentation generator uses a set of templates files to control the final rendering. This means that you can control precisely the rendering of the generated documentation. The templates used for generating the documentation can be found under <install_dir>/share/gps/docgen2. If you need a different layout as the proposed one, you can change directly those files.

The documentation generator can be invoked from two places inside GPS:

The Tools Menu
Generate project
Generate documentation for all files from the loaded project.
Generate projects & subprojects
Generate documentation for all files from the loaded project as well all its subprojects.
Generate current file
Generate documentation for the file you are currently editing.
Generate for...
This will open a File Selector Dialog (see The File Selector) and documentation will be generated for the file you select.

The Contextual Menu
When relevant (depending on the context), right-clicking with your mouse will show a Documentation contextual menu.

From a source file contextual menu, you have one option called Generate for <filename>, that will generate documentation for this file and if needed its corresponding body (see The Preferences Dialog).

From a project contextual menu (see The Project View), you will have the choice between generating documentation for all files from the selected project only or from the selected project recursively.

You will find the list of all documentation options in The Preferences Dialog.

Restrictions
There are some restrictions in the generated documentation:

Furthermore, the documentation generator relies on the ALI files created by GNAT. Depending on the version of GNAT used, the following restrictions may or may not apply: