Project File Options

You can specify various options and information for your project in the meta-data of your project file. Quoting from the Markdown Meta-Data page (and not intending to give an example of the meta-data fields supported by FORD):

Meta-data consists of a series of keywords and values defined at the beginning of a markdown document like this:

Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         John Doe
Date:    October 2, 2007
blank-value: 
base_url: http://example.com

This is the first paragraph of the document.

The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank.

If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. [Note that these must be spaces and not tabs.]

The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank. All meta-data is stripped from the document prior to any further processing by Markdown.

The options which can be specified in the meta-data are listed below. Defaults are included in the description, if they exist.

####project The name of this project. (default: Fortran Project) ####summary A summary of the description of your project. If present it will be printed in a "Jumbotron" element at the top of the documentation index page. This will be processed by Markdown before being used. ####project_url The URL at which the documentation will be available. If left blank then relative URLs will be used for links. This can be used within any documentation with the macro |url|. (default: blank, i.e. relative links) ####project_dir The directories where the source-files are to be found for this project. These must not be a subdirectory of the output_dir (see below). Multiple directories can be listed, each on their own line. (default: ./src) ####output_dir The directory where the project output will be placed. Any content already present there will be deleted. (default: ./doc) ####media_dir A directory containing any images or other content which you will use or link to in your documentation. This will be placed at the root of your documentation file-tree, with the name "media". The URL of this directory can be accessed within your documentation using the macro |media|. ####md_base_dir The directory relative to which any "included" Markdown files' paths are specified. (default: directory containing the project file.) ####page_dir A directory containing markdown files to be processed into individuals pages within the documentation. See Writing Pages for details. ####css The path to a custom style-sheet which can be used to modify the appearance of the output. ####md_extensions The name of any Markdown extensions which you wish to be used when parsing your documentation. For example, 'markdown.extensions.toc'. Note that Markdown-Extra, CodeHilite, and Meta-Data are loaded by default. ####extensions File extensions which will be read by FORD for documentation. Each extension must be on its own line. (default: f90, f95, f03, f08, F90, F95, F03, F08) ####exclude Source files which should not be included in documentation. Each excluded file must be on its own line. Provide only the file-name, not the full path. ####exclude_dir Directories whose contents should not be included in documentation. Each excluded directory must be on its own line. Provide only the directory name. ####extra_vartypes Any extra types of variables which FORD should look for. This can be useful when using, for example, the PETSc library. Each variable type must be on its own line. ####preprocess If set to 'true', then any files with extensions in which all letters are upper case will be passed through the standard C preprocessor used by gfortran/gcc before being parsed for documentation. However, any source code displayed in the documentation will be taken from the unprocessed file. This feature requires gfortran to be installed on the system. (default: true) ####macro Macros to be provided to the C preprocessor when applying it to source files. Can take the form mac-name or mac-name=mac-value. Each macro must appear on its own line. ####warn If 'true', FORD will print warning messages for any undocumented items which it encounters and any time it can not find the source code for some item where it is requested as part of the documentation. (default: false) ####quiet If 'true', FORD will suppress all output documenting its progress. (default: false) ####docmark The symbol(s) following an exclaimation mark which designates that a comment contains documentation. For excample, if the docmark was !, comments would then be designated by !!. It should not be the same as any other docmark. (default: !) ####predocmark The symbol(s) following an exclaimation mark which designates that a comment contains documentation preceding the code which it is documenting. For excample, if the docmark was >, comments would then be designated by !>. It should not be the same as any other docmark. (default: >) ####docmark_alt The symbol(s) following an exclaimation mark which designate that the following set of comments, until the end of the block, are all documentation. This mark needs only to be used at the beginning of the block, after which all regular comments will be treated as documentation. For excample, if the docmark was *, comments would then be designated by !*. An example of such a block of documentation is provided.

!# This is an example. 
!  Here is another line of comments.
!  
!  History
! ----------
!  * 1/1/2000 Created

subroutine blah()

end subroutine blah

It should not be the same symbol as any other docmark. (default: *) ####predocmark_alt The symbol(s) following an exclaimation mark which designate the start of a block of documentation preceding the code which it is documenting and that all further comments within this block will be treated as documentation. For example, if the predocmark_alt was #, comments would then be designated by !#. It should not be the same as any other docmark. (default: |) ####display How much documentation should be printed. Options are 'public', 'private', 'protected', or any combination of those three. Each choice must be on its own line. If 'none' is present, then nothing will be displayed other than the programs, mnodules, and procedures contained within source files (i.e. procedures within modules will not be displayed). These choice can be overridden for a specific item using the documentation meta data, and those settings will be inherited by any items they contain. (default: 'public' and 'protected') ####source If set to 'true', then the syntax-highlighted source code will be displayed at the bottom of the documentation page for each procedure, program, and derived type. This behaviour can be overridden for a given item using the documentation meta data. FORD may not be able to extract the source code in all cases; see here for details. Note that this substantially increase run-time. (default: false) ####graph If set to 'true' then call-trees, dependency diagrams, and inheritance diagrams will be produced for the project. These require Graphviz to be installed. This behaviour can be overridden for a given item in the code using the documentation meta data. Note that this can increase run-time substantially. The following graphs are produced:

• For each module:
  • a graph showing the modules which it uses and, if a submodule, the (sub)modules it is descended from
  • a graph showing which modules use and which submodules descend from this one
• For each type:
  • a graph showing all type which it descends from or contains as a component
  • a graph showing all types which descend from or contain as a component this type
• For each procedure:
  • a graph showing all procedures called by this procedure and (for interfaces) any procedures which it provides an interface to
  • a graph showing all procedures which call this one or provide and interface to it
• For each program:
  • a graph showing the modules which are used by the program
  • a graph showing the procedures called by the program
• A graph showing all module use dependencies on the module list page
• A graph showing the inheritance structure of all derived types (and their use as components of other types) on the type list page
• A graph showing the call-tree for all programs and procedures on the procedure list page

Note that, at present, call-trees only work for procedural programming and will not identify any calls to type-bound procedures. (default: false)

####sort The order in which to display entities (variables, procedures, etc.) in the documentation. Options are (default: src)

• src: Order which they occur in source code
• alpha: Alphabetical order.
• permission: Display public first, then protected, then private. Within these categories, items are displayed in the same order as they occur in the source code.
• permission-alpha: Display public first, then protected, then private. Within these categories, items are displayed in alphabetical order.
• type: Sort variables (and functions) by type. For each time, items are displayed in the same order as they occur in the source code/
• type-alpha: Sort variables (and functions) by type. Within these categories, items are displayed in alphabetical order.

####extra_mods A list of modules (and their external documentation) which are not included in the project. An entry takes the form module_name:url where module_name is its name as it would appear in a use statement, and url is the location of its documentation. Any entity which uses this module will provide a link to the external documentation in the same way that it would provide a link to the documentation of a module in the project. ####lower If true then convert all non-string and non-comment source code to lower case prior to analyzing. (default: false) ####search If true then add a search feature to the documentation. This can be time-consuming, so you may want to turn it off for large projects. (default: true) ####version The version name/number of your project. ####year The year to display in the copyright notice. (default: the current year) ####project_github The URL of the Github repository for this project.
####project_bitbucket The URL of the BitBucket repository for this project. ####favicon The path to a custom favicon which will be used by the HTML documentation. If left blank, it will default to an icon for FORD. ####project_sourceforge The Sourceforge repository for this project.
####project_download A URL from which to download the source or binaries for this project. ####project_website The homepage for this project. ####author The name of the person(s) or organization who wrote this project. ####author_description A brief description of the author. You could provide biographical details or links to other work, for example. This will be processed by Markdown before being used. ####author_pic A picture of or avatar for the author. ####github The author's Github page. ####bitbucket The author's BitBucket page. ####facebook The author's Facebook profile. ####twitter The author's Twitter. ####google_plus The author's Google+ ####linkedin The author's LinkedIn profile. ####email The author's email address. ####website The author's website.

---

Project file options will be overriden by Command Line Options.See ./example-project-file.md for a sample project file.