Introduction

Documentation for V3FIT, including this page, is generated by using the Doxygen tool. Doxygen is a tool where a startard markup inserted into source code is used to generate documentation by scaning a source file. All new coding should be accompanied by corresponding doxygen documentation.

Pages

Pages of documentation are automatically generated when a doxygen marked up comment is associated with a piece of source code. Even when doxygen comments are missing, limited documentation can still be generated.

Inline Pages

In addition to source code documentation, Doxygen has the ability to generate separate pages. In this project there are several source code pages that contain user level documentation in an associated the source code file. For instance the page documenting the Namelist v3fit_main_nli definition, is generated from the source code file. By having the user documentation inline with the source code, it is hoped that documentation remains in sync with source code. It is recommended to reference any inline pages from the main page. By default, a reference will be placed on the related pages page.

External Pages

Other pages might not be aassoicated with a source code file. For instance, this page it self was not generated from a source code file. Instead, extra doxygen pages can be added to the documentation by adding a file with a ".dox" file ending in

Documents/Extra Doxygen Pages/

directory. When adding a new extra file, it is addvised to reference any extra pages from the "main page.dox" file. By default, a reference will be placed on the related pages page.

Doxygen Mark Up

Doxygen contains a wide array build in mark up tags. A full list of these takes can be found in the Doxygen Manual.

Aliases

Sometimes the built in mark up is insuffient to generate the desired formatting. In these special casses, HTML mark may be used. When generating multiple forms of documentation, Doxygen will translate the HTML to the native mark up of the desired output. Custom mark up commands maybe defined via aliases. For instance, tables throughout this documentation are generated through some defined aliases. More information about defining aliases may be found on custom commands page.

V3FIT Defined Aliases

`item`	Generate a table row with three columns.
`item2`	Generate a table row with two columns. Used to generate this table.
`item3`	Generate a table row with three columns. Used to generate table in the Command Line Arguments page.
`item4`	Generate a table row with three columns. Used to generate table in the Stellarator-Tools Build System page.
`table_section`	Generate a table with a subsection heading.
`begin_table`	Generate a table. Used to generate this table.
`end_table`	End the generatation of a table. Used to generate this table.
`table_subsection`	Generate a table with a subsubsection heading. Note this command ends a pervious table and needs to be used after a `begin_table` or `table_section` but before a `end_table` command.
`header`	Generate a header for a `item` row. Note headers are a separate open and closed table. Use before the `begin_table` or `table_section` commands.
`header2`	Generate a header for a `item3` row. Note headers are a separate open and closed table. Use before the `begin_table` or `table_section` commands.
`header3`	Generate a header for a `item4` row. Note headers are a separate open and closed table. Use before the `begin_table` or `table_section` commands.
`fixed_width`	Make text with a fixed width font. Used to generate this table.

Documentation Generation

The doxygen documentation can be generated by the build system. For more information about building documentation, see the Stellarator-Tools Build System page.

Configuration

The doxygen documentation generation is from the Doxyfile.in configureation file. Currently, doxygen is configured to generate HTML and RTF documentation. In the future, LaTeX documentation may be added as well. The build system is designed to read this file, configure a few setting. These settings are typically paths. That file is then copied and renamed to Doxyfile in the build directory.

Defining Aliases

Extra alises maybe added by editing the Doxyfile.in file to append to the ALIASES varyable.

ALIASES += name_of_aliase{# of args}="the code of the alias"

Table of Contents