FORD

https://forddocs.readthedocs.io/en/stable
Admin
FORD is an automatic documentation generator for modern Fortran programs, designed to produce...
Tokens:70,492
Snippets:594
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Run FORD Command-Line Tool

Source: https://forddocs.readthedocs.io/en/stable/user_guide/getting_started

This command shows how to execute the FORD tool from the command line, passing the project configuration file as an argument. FORD then processes the source code and generates HTML documentation.

```bash
$ ford my_project.md

```

--------------------------------

### Create FORD Project Configuration File (Markdown)

Source: https://forddocs.readthedocs.io/en/stable/user_guide/getting_started

This snippet shows a basic project configuration file for FORD, written in Markdown format. It specifies the project name and author. This file is used by FORD to understand project metadata.

```markdown
---
project: My Fortran project
author: Me
---

This is my Fortran project!

```

--------------------------------

### Install FORD using pip

Source: https://forddocs.readthedocs.io/en/stable/index

This command installs the FORD documentation generator using the pip package manager. Pip handles all dependencies automatically. It can be used to install FORD in a virtual environment if administrative rights are not available.

```bash
pip install ford

```

--------------------------------

### Running FORD Documentation Generator (Console)

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/getting_started

This console command shows how to execute the FORD documentation generator. It takes the project file (`my_project.md`) as an argument and processes the Fortran source files to create HTML documentation in the specified output directory.

```console
$ ford my_project.md
Reading file src/hello.f90

Processing documentation comments...
Correlating information from different parts of your project...

Creating HTML documentation...
Creating search index: 100%|███████████████████| 3/3 [00:00<00:00, 45.97/s]

Writing documentation to '/home/ford/hello/doc'...

Browse the generated documentation: file:///home/ford/hello/doc/index.html
```

--------------------------------

### Install FORD using Spack

Source: https://forddocs.readthedocs.io/en/stable/index

This command installs the FORD documentation generator using the Spack package manager. Spack is a flexible package manager that supports multiple versions and configurations of software.

```bash
spack install py-ford

```

--------------------------------

### Examples of FORD Link Syntax

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/writing_documentation

Provides concrete examples of how to use the FORD link syntax to refer to modules, procedures, and specific items within modules. It shows various levels of specificity for creating links.

```text
[[my_mod]]
[[my_mod(module)]]
[[my_function]]
[[my_function(function)]]
[[my_function(proc)]]
[[my_mod:my_function]]
[[my_mod(module):my_function]]
[[my_mod:my_function(function)]]
[[my_mod(module):my_function(function)]]
```

--------------------------------

### Good Documentation Metadata Example

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/documentation_meta_data

This example demonstrates the correct placement and format for documentation metadata at the top of a source file. Metadata should immediately follow the item declaration without any intervening blank lines.

```fortran
! Good
type :: cat
  !! author: C. MacMackin
  !! version: v0.2
  !!
  !! This data-type represents a cat.
```

--------------------------------

### FORD Project File Configuration (Text)

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/getting_started

This snippet shows a basic FORD project configuration file (`my_project.md`). It defines project metadata such as the project name and author. This file is used by FORD to understand the project's context and settings.

```text
---
project: My Fortran project
author: Me
---

This is my Fortran project!
```

--------------------------------

### Bad Documentation Metadata Example

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/documentation_meta_data

This example shows an incorrect way to format documentation metadata. It includes a blank line before the metadata, which FordDocs will not parse correctly. Metadata must be contiguous with the item declaration.

```fortran
! Bad
type :: cat
  !!
  !! author: C. MacMackin
  !! version: v0.2
  !!
  !! This data-type represents a cat.
```

--------------------------------

### Document Fortran Code with FORD Comments

Source: https://forddocs.readthedocs.io/en/stable/user_guide/getting_started

This Fortran code snippet demonstrates how to use FORD's special comment syntax (`!!`) to document code entities like programs, subroutines, and variables. FORD extracts these comments to generate documentation.

```fortran
program hello
  !! This is our program
  implicit none

  ! This is just a normal comment
  call say_hello("World!")

contains

  subroutine say_hello(name)
    !! Our amazing subroutine to say hello
    character(len=*), intent(in) :: name
      !! Who to say hello to
    write(*, '("Hello, ", a)') name
  end subroutine say_hello

end program hello

```

--------------------------------

### Install FORD using Homebrew (macOS)

Source: https://forddocs.readthedocs.io/en/stable/index

These commands update the Homebrew package manager and then install FORD on macOS. The `--HEAD` flag can be used to install the latest development branch from GitHub.

```bash
brew update
brew install FORD

```

```bash
brew install --HEAD FORD

```

--------------------------------

### Example of Alternate Documentation Block Marker

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Demonstrates the use of an alternate documentation marker (`!*`) to denote a block of comments that should be treated as documentation until the end of the block.

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

subroutine blah()

end subroutine blah
```

--------------------------------

### fpm.toml doc_license Option

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Example of setting the `doc_license` option in `fpm.toml`.

```toml
doc_license = "by-sa"
```

--------------------------------

### HTML Comment Example

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Demonstrates how to use HTML block comments within the markdown body of a project file, specifically after the metadata section.

```html
<!-- This is a multi line
comment!

wow
-->
```

--------------------------------

### fpm.toml Project Configuration

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Example of how to configure Ford project options within the `[extra.ford]` table in an `fpm.toml` file. Supports comments and multi-line strings.

```toml
[extra.ford]
project = "My Project"

# TOML allows comments, which is handy
summary = """
Splitting your summary over multiple lines
is much easier in TOML.

It also allows blank lines in multi-line strings.
"""

preprocess = true
display = ["public", "protected"]
max_frontpage_items = 4
# An array of inline tables:
extra_filetypes = [
  { extension = "cpp", comment = "//" },
  { extension = "sh", comment = "#", lexer = "bash" },
  { extension = "py", comment = "#", lexer = "python" },
]
```

--------------------------------

### FORD Source Code Extraction - Line Continuation Example

Source: https://forddocs.readthedocs.io/en/stable/user_guide/documentation_meta_data

This example shows how line continuation with '&' can affect source code extraction in FORD. While the argument list can be on a different line, other forms of line continuation might prevent successful extraction.

```fortran
subroutine &
  example (a)
  integer, intent(inout) :: a
  a = a + 1
  return
end subroutine example


```

--------------------------------

### Creating and Populating a Project Instance

Source: https://forddocs.readthedocs.io/en/stable/developers_guide/index

A `Project` instance represents a collection of all entities within a software project. It iterates through source files, identifies Fortran files, and preprocesses those requiring a preprocessor.

```python
class Project:
    def __init__(self, src_dir, extensions, extra_filetypes, fpp_extensions, preprocessor):
        self.src_dir = src_dir
        self.extensions = extensions
        self.extra_filetypes = extra_filetypes
        self.fpp_extensions = fpp_extensions
        self.preprocessor = preprocessor
        self.entities = []

        # ... logic to iterate over source files ...

    def _process_file(self, filepath):
        # ... logic to determine file type and create FortranSourceFile or GenericSource ...
        pass
```

--------------------------------

### Markdown Metadata doc_license Option

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Example of setting the `doc_license` option using Markdown metadata.

```yaml
doc_license: by-sa
```

--------------------------------

### FORD Metadata Example - Correct Usage

Source: https://forddocs.readthedocs.io/en/stable/user_guide/documentation_meta_data

This snippet demonstrates the correct way to include metadata at the beginning of a documentation block in FORD. Metadata keys are followed by a colon, and there should be no preceding documentation or blank lines.

```fortran
! Good
type :: cat
  !! author: C. MacMackin
  !! version: v0.2
  !!
  !! This data-type represents a cat.


```

--------------------------------

### HTML Comment Example

Source: https://forddocs.readthedocs.io/en/stable/user_guide/project_file_options

Illustrates how to use HTML block comments within the project file. These comments are ignored during processing and can span multiple lines.

```html
<!-- This is a multi line
comment!

wow
-->

```

--------------------------------

### Markdown Metadata Block Example

Source: https://forddocs.readthedocs.io/en/stable/user_guide/project_file_options

Demonstrates the structure and syntax for specifying project options within a Markdown metadata block. This block must appear at the top of the file and is terminated by a blank line or triple dashes.

```markdown
---
project: My Project
summary: This is a summary of the project
    split over multiple lines (without any
    blank lines!)
preprocess: true
display: public
         protected
max_frontpage_items: 4
extra_filetypes: cpp //
    sh # bash
    py # python
---

This is the first paragraph of the document.

```

--------------------------------

### TOML doc_license Configuration

Source: https://forddocs.readthedocs.io/en/stable/user_guide/project_file_options

Example of setting the documentation license using the TOML configuration file format. This option specifies the license under which the documentation is released.

```toml
doc_license = "by-sa"

```

--------------------------------

### Markdown doc_license Configuration

Source: https://forddocs.readthedocs.io/en/stable/user_guide/project_file_options

Example of setting the documentation license using Markdown metadata. This option specifies the license under which the documentation is released.

```markdown
doc_license: by-sa

```

--------------------------------

### Markdown Phony Link Comment Example

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Shows how to use markdown phony link comments for comments within the markdown body of a project file, after the metadata section.

```markdown
[comment 1 goes here, this will declare a phony link target. Just make sure not to reference the null anchor]:#
```

--------------------------------

### Fortran Documentation Comment Syntax

Source: https://forddocs.readthedocs.io/en/stable/user_guide/writing_documentation

Demonstrates the standard and preceding documentation comment syntax in Fortran using FORD. Documentation comments start with `!!` and are placed after the code. Preceding documentation uses `!>` on the first line.

```fortran
subroutine feed_pets(cats, dogs, food, angry)
    !! Feeds your cats and dogs, if enough food is available. If not enough
    !! food is available, some of your pets will get angry.

    ! Arguments
    integer, intent(in)  :: cats
        !! The number of cats to keep track of.
    integer, intent(in)  :: dogs
        !! The number of dogs to keep track of.
    real, intent(inout)  :: food
        !! The ammount of pet food (in kilograms) which you have on hand.
    integer, intent(out) :: angry
        !! The number of pets angry because they weren't fed.

    !...
    return
end subroutine feed_pets

```

--------------------------------

### Generating HTML Documentation Files

Source: https://forddocs.readthedocs.io/en/stable/developers_guide/index

The `Documentation` class utilizes Jinja2 templates to render the parsed project structure and processed documentation into final HTML files. This is the final step in generating the user-facing documentation.

```python
class Documentation:
    def __init__(self, project, template_dir):
        self.project = project
        self.template_dir = template_dir
        self.jinja_env = Environment(loader=FileSystemLoader(template_dir))

    def generate_html(self):
        # ... logic to load templates and render HTML pages ...
        for page in self.project.pages:
            template = self.jinja_env.get_template(page.template_name)
            html_content = template.render(page_data=page.data)
            # ... save html_content to file ...
            pass
```

--------------------------------

### File Extensions Configuration (TOML and Markdown)

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Lists file extensions (without the dot) that FORD should process for documentation. Supports both free-form and fixed-form code extensions. Examples show TOML and Markdown (YAML) formats.

```toml
extensions = ["f90", "f", "F90", "F"]
```

```yaml
extensions: f90
    f
    F90
    F
```

--------------------------------

### Source Code Extraction Example with Line Continuation

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/documentation_meta_data

This Fortran subroutine illustrates a scenario where source code extraction might fail due to line continuation in the subroutine declaration. FordDocs requires the item name and type to be on the same line for successful extraction.

```fortran
subroutine &
  example (a)
  integer, intent(inout) :: a
  a = a + 1
  return
end subroutine example
```

--------------------------------

### Fortran Source Code with FORD Comments (Fortran)

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/getting_started

This Fortran code snippet (`src/hello.f90`) demonstrates how to embed FORD documentation comments within Fortran source files. Comments starting with `!!` are parsed by FORD to generate documentation for programs, subroutines, and variables.

```fortran
program hello
  !! This is our program
  implicit none

  ! This is just a normal comment
  call say_hello("World!")

contains

  subroutine say_hello(name)
    !! Our amazing subroutine to say hello
    character(len=*), intent(in) :: name
      !! Who to say hello to
    write(*, '("Hello, ", a)') name
  end subroutine say_hello

end program hello
```

--------------------------------

### ford.initialize()

Source: https://forddocs.readthedocs.io/en/stable/api/ford

Initializes the FORD application by parsing and checking configurations, obtaining global documentation, and setting up the Markdown reader.

```APIDOC
## POST /ford/initialize

### Description
Initializes FORD by parsing and checking configurations, getting project documentation, and creating the Markdown reader.

### Method
POST

### Endpoint
/ford/initialize

### Parameters
#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for initialization."
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful initialization.

#### Response Example
```json
{
  "message": "FORD initialized successfully."
}
```
```

--------------------------------

### Load Settings from Markdown - Python

Source: https://forddocs.readthedocs.io/en/stable/api/ford.settings

Loads project settings from a Markdown file. It takes the directory, the project file, and an optional filename as input, returning the project settings and a string.

```python
ford.settings.load_markdown_settings(_directory_, _project_file_, _filename=None)
```

--------------------------------

### ford.load_settings()

Source: https://forddocs.readthedocs.io/en/stable/api/ford

Loads FORD settings from `fpm.toml` or project file metadata. It processes project documentation and returns settings.

```APIDOC
## POST /ford/load_settings

### Description
Loads Ford settings from `fpm.toml` or metadata in the supplied project file. Converts markdown project files.

### Method
POST

### Endpoint
/ford/load_settings

### Parameters
#### Request Body
- **proj_docs** (string) - Text of the project file.
- **directory** (string) - Optional. The project directory. Defaults to the current directory.
- **filename** (string) - Optional. The name of the settings file.

### Request Example
```json
{
  "proj_docs": "# My Project\nThis is a sample project file.",
  "directory": ".",
  "filename": "fpm.toml"
}
```

### Response
#### Success Response (200)
- **proj_docs** (string) - Text of the project file converted from markdown.
- **proj_data** (object) - Project settings.

#### Response Example
```json
{
  "proj_docs": "# My Project\nThis is a sample project file.",
  "proj_data": {
    "setting1": "value1",
    "setting2": "value2"
  }
}
```
```

--------------------------------

### Load Settings from TOML - Python

Source: https://forddocs.readthedocs.io/en/stable/api/ford.settings

Loads Ford settings from the `fpm.toml` file located within a specified directory. Settings are expected to be under the `[extra.ford]` table. Returns `Optional[ProjectSettings]`.

```python
ford.settings.load_toml_settings(_directory_)
```

--------------------------------

### ProjectSettings Class

Source: https://forddocs.readthedocs.io/en/stable/api/ford.settings

Manages project-wide settings for documentation generation.

```APIDOC
## ProjectSettings Class

### Description
Manages project-wide settings for documentation generation. This class holds configurations for project metadata, output directories, extensions, and various other options that influence the documentation build process.

### Class Definition
`class ford.settings.ProjectSettings(_alias=<factory>_, _author=None_, _author_description=None_, _author_pic=None_, _bitbucket=None_, _coloured_edges=False_, _copy_subdir=<factory>_, _creation_date='%Y-%m-%dT%H:%M:%S.%f%z'_ , _css=None_, _dbg=True_, _directory=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/forddocs/checkouts/stable/docs')_, _display=<factory>_, _doc_license='', _docmark='!', _doxygen=True_, _docmark_alt='*', _email=None_, _encoding='utf-8'_ , _exclude=<factory>_, _exclude_dir=<factory>_, _extensions=<factory>_, _external=<factory>_, _externalize=False_, _extra_filetypes=<factory>_, _extra_mods=<factory>_, _facebook=None_, _favicon=PosixPath('favicon.png')_, _fixed_extensions=<factory>_, _fixed_length_limit=True_, _force=False_, _fpp_extensions=<factory>_, _github=None_, _gitlab=None_, _gitter_sidecar=None_, _google_plus=None_, _graph=False_, _graph_dir=None_, _graph_maxdepth=10000_, _graph_maxnodes=1000000000_, _hide_undoc=False_, _html_template_dir=<factory>_, _incl_src=True_, _include=<factory>_, _license='', _linkedin=None_, _lower=False_, _macro=<factory>_, _mathjax_config=None_, _max_frontpage_items=10_, _md_base_dir=PosixPath('.')_, _md_extensions=<factory>_, _media_dir=None_, _output_dir=PosixPath('doc')_, _page_dir=None_, _parallel=2_, _predocmark=' >'_, _predocmark_alt='|'_, _preprocess=True_, _preprocessor='pcpp -D__GFORTRAN__ --passthru-comments'_, _print_creation_date=False_, _privacy_policy_url=None_, _proc_internals=False_, _project='Fortran Program'_, _project_bitbucket=None_, _project_download=None_, _project_github=None_, _project_gitlab=None_, _project_sourceforge=None_, _project_url='', _project_website=None_, _quiet=False_, _revision=None_, _search=True_, _show_proc_parent=False_, _sort='src'_ , _source=False_, _src_dir=<factory>_, _summary=None_, _terms_of_service_url=None_, _twitter=None_, _version=None_, _warn=False_, _website=None_, _year='2025'_)

Bases: `object`

### Attributes
- **alias** (`Dict[str, str]`) - Aliases for project elements.
- **author** (`Optional[str]`) - The main author of the project.
- **author_description** (`Optional[str]`) - Description of the author.
- **author_pic** (`Optional[str]`) - Path to the author's picture.
- **bitbucket** (`Optional[str]`) - Bitbucket repository URL.
- **coloured_edges** (`bool`) - Whether to use colored edges in graphs.
- **copy_subdir** (`List[Path]`) - Subdirectories to copy.
- **creation_date** (`str`) - The format string for the creation date.
- **css** (`Optional[Path]`) - Path to custom CSS file.
- **dbg** (`bool`) - Enable debug mode.
- **directory** (`Path`) - The documentation directory.
- **display** (`List[str]`) - List of display options.
- **doc_license** (`str`) - The license for the documentation.
- **docmark** (`str`) - The documentation mark character.
- **docmark_alt** (`str`) - Alternative documentation mark character.
- **doxygen** (`bool`) - Enable Doxygen integration.
- **email** (`Optional[str]`) - Contact email address.
- **encoding** (`str`) - The file encoding to use.
- **exclude** (`List[str]`) - List of files or directories to exclude.
- **exclude_dir** (`List[Path]`) - List of directories to exclude.
- **extensions** (`List[str]`) - List of file extensions to process.
- **external** (`Dict[str, str]`) - Dictionary for external links.
- **externalize** (`bool`) - Whether to externalize links.
- **extra_filetypes** (`Dict[str, ExtraFileType]`) - Dictionary of extra file types.
- **extra_mods** (`Dict[str, str]`) - Dictionary for extra modules.
- **facebook** (`Optional[str]`) - Facebook profile URL.
- **favicon** (`Path`) - Path to the favicon.
- **fixed_extensions** (`List[str]`) - List of fixed file extensions.
- **fixed_length_limit** (`bool`) - Whether to enforce fixed length limits.
- **force** (`bool`) - Force regeneration.
- **fpp_extensions** (`List[str]`) - List of FPP extensions.
- **github** (`Optional[str]`) - GitHub repository URL.
- **gitlab** (`Optional[str]`) - GitLab repository URL.
- **gitter_sidecar** (`Optional[str]`) - Gitter sidecar configuration.
- **google_plus** (`Optional[str]`) - Google+ profile URL.
- **graph** (`bool`) - Enable graph generation for the project.
- **graph_dir** (`Optional[Path]`) - Directory for generated graphs.
- **graph_maxdepth** (`int`) - Maximum depth for graph generation.
- **graph_maxnodes** (`int`) - Maximum number of nodes for graph generation.
- **hide_undoc** (`bool`) - Whether to hide undocumented elements.
- **html_template_dir** (`List[Path]`) - Directories for HTML templates.
- **incl_src** (`bool`) - Whether to include source code.
- **include** (`List[str]`) - List of files or directories to include.
- **license** (`str`) - The project license.
- **linkedin** (`Optional[str]`) - LinkedIn profile URL.
- **lower** (`bool`) - Convert output to lowercase.
- **macro** (`List[str]`) - List of macros to define.
- **mathjax_config** (`Optional[str]`) - MathJax configuration string.
- **max_frontpage_items** (`int`) - Maximum items on the front page.
- **md_base_dir** (`Path`) - Base directory for markdown files.
- **md_extensions** (`List[str]`) - List of markdown extensions.
- **media_dir** (`Optional[Path]`) - Directory for media files.
- **output_dir** (`Path`) - The output directory for generated documentation.
- **page_dir** (`Optional[Path]`) - Directory for page files.
- **parallel** (`int`) - Number of parallel processes to use.
- **predocmark** (`str`) - Pre-documentation mark character.
- **predocmark_alt** (`str`) - Alternative pre-documentation mark character.
- **preprocess** (`bool`) - Enable preprocessing.
- **preprocessor** (`str`) - The preprocessor command.
- **print_creation_date** (`bool`) - Whether to print the creation date.
- **privacy_policy_url** (`Optional[str]`) - URL for the privacy policy.
- **proc_internals** (`bool`) - Whether to process internal elements.
- **project** (`str`) - The name of the project.
- **project_bitbucket** (`Optional[str]`) - Project's Bitbucket URL.
- **project_download** (`Optional[str]`) - Project download URL.
- **project_github** (`Optional[str]`) - Project's GitHub URL.
- **project_gitlab** (`Optional[str]`) - Project's GitLab URL.
- **project_sourceforge** (`Optional[str]`) - Project's SourceForge URL.
- **project_url** (`str`) - The project's main URL.
- **project_website** (`Optional[str]`) - Project website URL.
- **quiet** (`bool`) - Enable quiet mode.
- **revision** (`Optional[str]`) - Project revision number.
- **search** (`bool`) - Enable search functionality.
- **show_proc_parent** (`bool`) - Whether to show the parent of processed elements.
- **sort** (`str`) - Sorting order for elements.
- **source** (`bool`) - Whether to include source code.
- **src_dir** (`List[Path]`) - Source directories.
- **summary** (`Optional[str]`) - A summary description of the project.
- **terms_of_service_url** (`Optional[str]`) - URL for the terms of service.
- **twitter** (`Optional[str]`) - Twitter profile URL.
- **version** (`Optional[str]`) - The project version.
- **warn** (`bool`) - Enable warnings.
- **website** (`Optional[str]`) - Website URL.
- **year** (`str`) - The copyright year.
```

--------------------------------

### Regular Expression for FORD Admonition Start

Source: https://forddocs.readthedocs.io/en/stable/api/ford.md_admonition

Defines the regular expression pattern used to identify the start of a FORD style admonition. It captures the indentation, the admonition type (note, warning, todo, bug, history), and any text on the same line as the type marker.

```python
ADMONITION_RE = re.compile('(?P<indent>\s*)\n @(?P<type>note|warning|todo|bug|history)\n (?P<posttxt>.*)\n ', re.IGNORECASE|re.VERBOSE)
```

--------------------------------

### ProjectSettings Configuration

Source: https://forddocs.readthedocs.io/en/stable/api/ford.settings

Details the comprehensive configuration options for the entire project, covering various aspects like source control, output, and display.

```APIDOC
## ProjectSettings Configuration

### Description
Comprehensive settings that govern the behavior and output of the entire project documentation generation.

### Class
`ProjectSettings`

### Attributes
- **alias** (string) - An alias for the project.
- **author** (string) - The primary author of the project.
- **author_description** (string) - A description of the author.
- **author_pic** (string) - Path to the author's picture.
- **bitbucket** (string) - Bitbucket repository URL.
- **coloured_edges** (boolean) - Whether to use colored edges in graphs.
- **copy_subdir** (boolean) - Whether to copy subdirectories.
- **creation_date** (string) - The creation date of the project.
- **css** (string) - Path to custom CSS file.
- **dbg** (boolean) - Enable debugging output.
- **directory** (string) - The project directory.
- **display** (boolean) - Controls overall project display.
- **doc_license** (string) - The license for the documentation.
- **docmark** (string) - Docmark configuration string.
- **docmark_alt** (string) - Alternative Docmark configuration string.
- **doxygen** (boolean) - Enable Doxygen integration.
- **email** (string) - Contact email address.
- **encoding** (string) - File encoding.
- **exclude** (list) - List of files/directories to exclude.
- **exclude_dir** (list) - List of directories to exclude.
- **extensions** (list) - List of file extensions to process.
- **external** (boolean) - Whether to treat links as external.
- **externalize** (boolean) - Whether to externalize links.
- **extra_filetypes** (list) - List of `ExtraFileType` configurations.
- **extra_mods** (list) - List of extra modules to include.
- **extra_vartypes** (list) - List of extra variable types.
- **facebook** (string) - Facebook profile URL.
- **favicon** (string) - Path to the favicon.
- **fixed_extensions** (list) - List of fixed file extensions.
- **fixed_length_limit** (integer) - Limit for fixed length strings.
- **force** (boolean) - Force overwriting existing files.
- **fpp_extensions** (list) - List of FPP file extensions.
- **github** (string) - GitHub repository URL.
- **gitlab** (string) - GitLab repository URL.
- **gitter_sidecar** (boolean) - Enable Gitter sidecar chat.
- **google_plus** (string) - Google+ profile URL.
- **graph** (boolean) - Whether to generate graphs.
- **graph_dir** (string) - Directory to save graphs.
- **graph_maxdepth** (integer) - Maximum depth for graph generation.
- **graph_maxnodes** (integer) - Maximum nodes for graph generation.
- **hide_undoc** (boolean) - Hide undocumented elements.
- **html_template_dir** (string) - Directory for HTML templates.
- **incl_src** (boolean) - Include source code in output.
- **include** (list) - List of files/directories to include.
- **license** (string) - Project license.
- **linkedin** (string) - LinkedIn profile URL.
- **lower** (boolean) - Convert output to lowercase.
- **macro** (string) - Macro definition string.
- **mathjax_config** (string) - MathJax configuration string.
- **max_frontpage_items** (integer) - Maximum items on the front page.
- **md_base_dir** (string) - Base directory for markdown files.
- **md_extensions** (list) - List of markdown extensions to use.
- **media_dir** (string) - Directory for media files.
- **output_dir** (string) - Directory for output files.
- **page_dir** (string) - Directory for page files.
- **parallel** (boolean) - Enable parallel processing.
- **predocmark** (string) - Predocmark configuration string.
- **predocmark_alt** (string) - Alternative Predocmark configuration string.
- **preprocess** (boolean) - Enable preprocessing.
- **preprocessor** (string) - Path to the preprocessor executable.
- **print_creation_date** (boolean) - Print creation date in output.
- **privacy_policy_url** (string) - URL for the privacy policy.
- **proc_internals** (boolean) - Whether to process internal elements.
- **project_bitbucket** (string) - Bitbucket project URL.
- **project_download** (string) - Project download URL.
- **project_github** (string) - GitHub project URL.
- **project_gitlab** (string) - GitLab project URL.
- **project_sourceforge** (string) - SourceForge project URL.
- **project_url** (string) - General project URL.
- **project_website** (string) - Project website URL.
- **quiet** (boolean) - Suppress non-error output.
- **relative** (boolean) - Use relative paths.
- **revision** (string) - Project revision number.
- **search** (boolean) - Enable search functionality.
- **show_proc_parent** (boolean) - Show parent of processed elements.
- **sort** (boolean) - Sort output.
- **source** (string) - Source directory.
- **src_dir** (string) - Source code directory.
- **summary** (string) - Project summary.
- **terms_of_service_url** (string) - URL for the terms of service.
- **twitter** (string) - Twitter profile URL.
- **version** (string) - Project version.
- **warn** (boolean) - Enable warnings.
- **website** (string) - Project website URL.
- **year** (string) - Project year.

### Methods
- **from_markdown_metadata()**: Creates ProjectSettings from markdown metadata.
- **normalise_paths()**: Normalizes project paths.

```

--------------------------------

### get_mod_procs Function

Source: https://forddocs.readthedocs.io/en/stable/api/ford.sourceform

Retrieves module procedures from an interface. This function is used to get a list of `FortranModuleProcedureReference` objects.

```python
ford.sourceform.get_mod_procs(_source_, _names_, _parent_)
    
    Get module procedures from an interface 

    Return type:
        
    List[FortranModuleProcedureReference]

```

--------------------------------

### Run Ford Command - Shell

Source: https://forddocs.readthedocs.io/en/stable/user_guide/project_file_options

This command initiates the FORD documentation generation process for a specified project file. It's the primary way to run FORD.

```shell
$ ford <project-file.md>

```

--------------------------------

### get_page_tree Function

Source: https://forddocs.readthedocs.io/en/stable/api/ford.pagetree

Retrieves the page tree structure starting from a given top directory.

```APIDOC
## get_page_tree Function

### Description
Retrieves the page tree structure starting from a given top directory.

### Method
Function

### Endpoint
N/A (Function definition)

### Parameters
- **_topdir_** (str) - Required - The top-level directory to start building the page tree from.
- **_proj_copy_subdir_** (str) - Required - The project copy subdirectory.
- **_output_dir_** (str) - Required - The output directory.
- **_md_** (object) - Required - Metadata object.
- **_progress_** (object) - Optional - A progress indicator object.
- **_parent_** (object) - Optional - The parent PageNode object.
- **_encoding_** (str) - Optional - The encoding to use (default: 'utf-8').

### Returns
- **PageNode** - The root PageNode of the generated page tree.
```

--------------------------------

### Utility Functions

Source: https://forddocs.readthedocs.io/en/stable/api/ford.settings

Documentation for various utility functions used for type conversion and settings loading.

```APIDOC
## Utility Functions

### Description
Provides a collection of utility functions for converting settings, determining type compatibility, and loading configuration from different file formats.

### Method
N/A (Standalone Functions)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```json
{
  "example": "N/A for utility functions"
}
```

### Response
#### Success Response (200)
Functions return values based on their specific implementation.

#### Response Example
```json
{
  "example": "N/A for utility functions"
}
```

### Available Functions:
- **convert_setting()**: Converts a setting value.
- **convert_to_bool()**: Converts a value to a boolean.
- **convert_types_from_commandarguments()**: Converts types from command-line arguments.
- **convert_types_from_metapreprocessor()**: Converts types from meta preprocessor.
- **default_cpus()**: Returns the default number of CPUs.
- **is_optional_type()**: Checks if a type is optional.
- **is_same_type()**: Checks if two types are the same.
- **load_markdown_settings()**: Loads settings from a markdown file.
- **load_toml_settings()**: Loads settings from a TOML file.
```

--------------------------------

### fpm.toml macro List Option

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/project_file_options

Example of setting a list option like `macro` in `fpm.toml`.

```toml
macro = [
  "HAS_DECREMENT",
  "DIMENSION=3",
]
```

--------------------------------

### Documentation Class

Source: https://forddocs.readthedocs.io/en/stable/api/ford.output

Represents and handles the creation of the documentation files from a project.

```APIDOC
## Class ford.output.Documentation

### Description
Represents and handles the creation of the documentation files from a project.

### Attributes
- **settings** (any) - Documentation settings.
- **proj_docs** (any) - Project documentation data.
- **project** (FortranProject) - The FortranProject object.
- **pagetree** (any) - The page tree structure.

### Methods
- **writeout()** - Writes out the documentation files. Return type: `None`.
```

--------------------------------

### remove_doxy Function

Source: https://forddocs.readthedocs.io/en/stable/api/ford.sourceform

Removes Doxygen comments that start with an '@' identifier from the main comment block. It returns a list of strings representing the cleaned comment block.

```python
ford.sourceform.remove_doxy(_source_)
    
    Remove doxygen comments with an @ identifier from main comment block. 

    Return type:
        
    List[str]

```

--------------------------------

### read_docstring Function

Source: https://forddocs.readthedocs.io/en/stable/api/ford.sourceform

Reads a contiguous block of documentation comments, typically starting with a specific marker. It returns a list of strings, where each string is a line of the docstring.

```python
ford.sourceform.read_docstring(_source_, _docmark_)
    
    Read a contiguous docstring 

    Return type:
        
    List[str]

```

--------------------------------

### Run FORD Command - Console

Source: https://forddocs.readthedocs.io/en/stable/_sources/user_guide/running_ford

The basic command to run FORD, taking a project file as input. This command initiates the documentation generation process. Ensure the project file path is correct.

```console
$ ford project-file.md
```

--------------------------------

### FORD API Reference - T

Source: https://forddocs.readthedocs.io/en/stable/genindex

This section details attributes, classes, and methods starting with the letter 'T' within the FORD tool, such as template, terms_of_service_url, and translate_links.

```APIDOC
## FORD API Reference - T

### Description
Details attributes, classes, and methods starting with 'T'.

### Endpoints
This section lists various components related to 'T'.

#### Attributes
- **terms_of_service_url** (ford.settings.ProjectSettings attribute)
- **title** (ford.settings.EntitySettings attribute)
- **twitter** (ford.settings.ProjectSettings attribute)
- **type** (ford.md_admonition.AdmonitionPreprocessor.Admonition attribute)
- **TYPE_RE** (ford.sourceform.FortranContainer attribute)

#### Classes
- **Tipue_Search_JSON_Generator** (class in ford.tipue_search)
- **TypeGraph** (class in ford.graphs)
- **TypeList** (class in ford.output)
- **TypeNode** (class in ford.graphs)
- **TypePage** (class in ford.output)

#### Methods
- **translate_doxy_meta()** (in module ford.sourceform)
- **translate_links()** (in module ford.sourceform)
- **traverse()** (in module ford.utils)

#### Properties
- **template** (ford.output.BasePage property)
- **template_path** (ford.output.AbsIntList attribute)

#### Other
- **(ford.output.AbsIntPage attribute)**
- **(ford.output.BasePage property)**
- **(ford.output.BlockList attribute)**
- **(ford.output.BlockPage attribute)**
- **(ford.output.FileList attribute)**
- **(ford.output.FilePage attribute)**
- **(ford.output.GenericInterfacePage attribute)**
- **(ford.output.IndexPage attribute)**
- **(ford.output.InterfacePage attribute)**
- **(ford.output.ModList attribute)**
- **(ford.output.ModulePage attribute)**
- **(ford.output.NamelistList attribute)**
- **(ford.output.NamelistPage attribute)**
- **(ford.output.PagetreePage attribute)**
- **(ford.output.ProcedurePage attribute)**
- **(ford.output.ProcList attribute)**
- **(ford.output.ProgList attribute)**
- **(ford.output.ProgPage attribute)**
- **(ford.output.SearchPage attribute)**
- **(ford.output.TypeList attribute)**
- **(ford.output.TypePage attribute)**
- **truncated** (ford.graphs.FortranGraph attribute)

```

--------------------------------

### ford.run()

Source: https://forddocs.readthedocs.io/en/stable/api/ford

Executes the main logic of the FORD application after all configurations and arguments have been processed.

```APIDOC
## POST /ford/run

### Description
Executes the main FORD process.

### Method
POST

### Endpoint
/ford/run

### Parameters
#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for run."
}
```

### Response
#### Success Response (200)
- **result** (string) - Indicates the outcome of the run process.

#### Response Example
```json
{
  "result": "FORD run completed successfully."
}
```
```

--------------------------------

### FORD API Reference - U

Source: https://forddocs.readthedocs.io/en/stable/genindex

This section details attributes, classes, and methods starting with the letter 'U' within the FORD tool, such as update, url, and USE_RE.

```APIDOC
## FORD API Reference - U

### Description
Details attributes, classes, and methods starting with 'U'.

### Endpoints
This section lists various components related to 'U'.

#### Attributes
- **USE_RE** (ford.sourceform.FortranContainer attribute)

#### Classes
- **UsedByGraph** (class in ford.graphs)
- **UsesGraph** (class in ford.graphs)

#### Methods
- **update()** (ford.settings.EntitySettings method)

#### Properties
- **url** (ford.pagetree.PageNode property)

```

--------------------------------

### FORD API Reference - S

Source: https://forddocs.readthedocs.io/en/stable/genindex

This section details attributes, classes, and methods starting with the letter 'S' within the FORD tool, such as SC_RE, search, set_current, and sort.

```APIDOC
## FORD API Reference - S

### Description
Details attributes, classes, and methods starting with 'S'.

### Endpoints
This section lists various components related to 'S'.

#### Attributes
- **SC_RE** (ford.reader.FortranReader attribute)
- **search** (ford.settings.ProjectSettings attribute)
- **show_proc_parent** (ford.settings.ProjectSettings attribute)
- **since** (ford.settings.EntitySettings attribute)
- **sort** (ford.settings.ProjectSettings attribute)
- **source** (ford.settings.EntitySettings attribute)
- **SPLIT_RE** (ford.sourceform.FortranBase attribute)
- **src_dir** (ford.settings.ProjectSettings attribute)
- **start_idx** (ford.md_admonition.AdmonitionPreprocessor.Admonition attribute)
- **strlen** (ford.sourceform.ParsedType attribute)
- **SUBCALL_RE** (ford.sourceform.FortranContainer attribute)
- **SUBMODULE_RE** (ford.sourceform.FortranContainer attribute)
- **SUBROUTINE_RE** (ford.sourceform.FortranContainer attribute)
- **summary** (ford.settings.EntitySettings attribute)

#### Classes
- **SearchPage** (class in ford.output)
- **StripedTableCSSExtension** (class in ford.md_striped_table)
- **StripedTableCSSTreeprocessor** (class in ford.md_striped_table)
- **SubmodNode** (class in ford.graphs)
- **Tipue_Search_JSON_Generator** (class in ford.tipue_search)
- **TypeGraph** (class in ford.graphs)
- **TypeList** (class in ford.output)
- **TypeNode** (class in ford.graphs)
- **TypePage** (class in ford.output)

#### Methods
- **set_current()** (ford.utils.ProgressBar method)
- **sort_components()** (ford.sourceform.FortranBase method)
- **stdout_redirector()** (in module ford)
- **str_to_bool()** (in module ford.utils)
- **strip_paren()** (in module ford.utils)

#### Properties
- **source_file** (ford.sourceform.FortranBase property)

#### Other
- **(ford.settings.ProjectSettings attribute)**
- **(ford.settings.EntitySettings attribute)**

```

--------------------------------

### FORD API Reference - R

Source: https://forddocs.readthedocs.io/en/stable/genindex

This section details attributes, classes, and methods starting with the letter 'R' within the FORD tool, such as RANKDIR, RE, read_docstring, register, and render.

```APIDOC
## FORD API Reference - R

### Description
Details attributes, classes, and methods starting with 'R'.

### Endpoints
This section lists various components related to 'R'.

#### Attributes
- **RANKDIR** (ford.graphs.CalledByGraph attribute)
- **RE** (ford.md_admonition.FordAdmonitionProcessor attribute)
- **relative** (ford.settings.ProjectSettings attribute)
- **RENAME_RE** (ford.sourceform.FortranModule attribute)
- **rest** (ford.sourceform.ParsedType attribute)
- **revision** (ford.settings.ProjectSettings attribute)
- **SPLIT_RE** (ford.sourceform.FortranBase attribute)
- **start_idx** (ford.md_admonition.AdmonitionPreprocessor.Admonition attribute)
- **strlen** (ford.sourceform.ParsedType attribute)
- **SUBCALL_RE** (ford.sourceform.FortranContainer attribute)
- **SUBMODULE_RE** (ford.sourceform.FortranContainer attribute)
- **SUBROUTINE_RE** (ford.sourceform.FortranContainer attribute)
- **summary** (ford.settings.EntitySettings attribute)
- **TYPE_RE** (ford.sourceform.FortranContainer attribute)

#### Classes
- **RelativeLinksExtension** (class in ford._markdown)
- **RelativeLinksTreeProcessor** (class in ford._markdown)
- **StripedTableCSSExtension** (class in ford.md_striped_table)
- **StripedTableCSSTreeprocessor** (class in ford.md_striped_table)
- **SubmodNode** (class in ford.graphs)
- **Tipue_Search_JSON_Generator** (class in ford.tipue_search)
- **TypeGraph** (class in ford.graphs)
- **TypeList** (class in ford.output)
- **TypeNode** (class in ford.graphs)
- **TypePage** (class in ford.output)

#### Methods
- **read_docstring()** (in module ford.sourceform)
- **read_metadata()** (ford.sourceform.FortranBase method)
- **register()** (ford.graphs.GraphData method)
- **relative_url()** (in module ford.output)
- **remove_doxy()** (in module ford.sourceform)
- **remove_kind_suffix()** (in module ford.sourceform)
- **remove_last_batch()** (ford.sourceform.Associations method)
- **remove_prefixes()** (in module ford.sourceform)
- **render()** (ford.output.BasePage method)
- **reset()** (ford._markdown.MetaMarkdown method)
- **routines** (ford.sourceform.FortranBase property)
- **run()** (ford._markdown.AliasPreprocessor method)

#### Properties
- **routines** (ford.sourceform.FortranBase property)

#### Other
- **(ford.graphs.CalledByGraph attribute)**
- **(ford.graphs.CallGraph attribute)**
- **(ford.graphs.CallsGraph attribute)**
- **(ford.graphs.FortranGraph attribute)**
- **(ford.graphs.GraphManager method)**
- **(ford.output)**
- **(ford.output.BasePage method)**
- **(ford.output.DocPage method)**
- **(ford.output.ListPage method)**
- **(ford.output.ListTopPage method)**
- **(ford.output.PagetreePage method)**
- **(ford._markdown.MetaMarkdown method)**
- **(ford.md_admonition.AdmonitionPreprocessor method)**
- **(ford.md_striped_table.StripedTableCSSTreeprocessor method)**
- **(in module ford)**
- **(ford._markdown.RelativeLinksTreeProcessor method)**
- **(ford.md_admonition.AdmonitionPreprocessor method)**
- **(ford.md_striped_table.StripedTableCSSTreeprocessor method)**
- **subroutines** (ford.sourceform.FortranInterface attribute)
- **summary** (ford.settings.ProjectSettings attribute)
- **template** (ford.output.BasePage property)
- **template_path** (ford.output.AbsIntList attribute)
- **terms_of_service_url** (ford.settings.ProjectSettings attribute)
- **title** (ford.settings.EntitySettings attribute)
- **translate_doxy_meta()** (in module ford.sourceform)
- **translate_links()** (in module ford.sourceform)
- **traverse()** (in module ford.utils)
- **truncated** (ford.graphs.FortranGraph attribute)
- **twitter** (ford.settings.ProjectSettings attribute)
- **type** (ford.md_admonition.AdmonitionPreprocessor.Admonition attribute)

```
Tokens:
Raw