aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSebastian Ehlert <28669218+awvwgk@users.noreply.github.com>2020-11-10 21:34:04 +0100
committerGitHub <noreply@github.com>2020-11-10 21:34:04 +0100
commite034ad418ad8da3754b80a9673b7017e9798b2a0 (patch)
treedd367c479e5b1e7c5e9b43b5b9f2366528709460
parentd569a89d7d059a5ba914e51d6fd7b32132b33c5e (diff)
downloadfpm-e034ad418ad8da3754b80a9673b7017e9798b2a0.tar.gz
fpm-e034ad418ad8da3754b80a9673b7017e9798b2a0.zip
Add automatic documentation for Fortran fpm (#209)
- create docs.md as input for FORD - fix docstrings and comment style for FORD - workaround FORD bug by adding whitespace to table headers - add manifest reference to FORD pages - apply ugly workaround to not replace array of tables with links
-rw-r--r--PACKAGING.md18
-rw-r--r--doc/Contributing.md5
-rw-r--r--doc/License.md5
-rw-r--r--doc/Manifest.md6
-rw-r--r--doc/Packaging.md5
-rw-r--r--doc/index.md3
-rw-r--r--doc/media/favicon.icobin0 -> 16958 bytes
-rw-r--r--docs.md32
-rw-r--r--fpm/src/fpm.f9020
-rw-r--r--fpm/src/fpm/cmd/new.f904
-rw-r--r--fpm/src/fpm/manifest.f9014
-rw-r--r--fpm/src/fpm/manifest/build_config.f9016
-rw-r--r--fpm/src/fpm/manifest/dependency.f9046
-rw-r--r--fpm/src/fpm/manifest/executable.f9020
-rw-r--r--fpm/src/fpm/manifest/library.f9016
-rw-r--r--fpm/src/fpm/manifest/package.f9056
-rw-r--r--fpm/src/fpm/manifest/test.f9028
-rw-r--r--fpm/src/fpm/toml.f9024
-rw-r--r--manifest-reference.md8
19 files changed, 191 insertions, 135 deletions
diff --git a/PACKAGING.md b/PACKAGING.md
index f5f28e3..44a0c02 100644
--- a/PACKAGING.md
+++ b/PACKAGING.md
@@ -456,7 +456,7 @@ copyright = "2020 Jane Programmer"
[library]
source-dir="src"
-[[executable]]
+[[ executable ]]
name="math_constants"
source-dir="app"
main="main.f90"
@@ -487,12 +487,12 @@ copyright = "2020 Jane Programmer"
[library]
source-dir="src"
-[[executable]]
+[[ executable ]]
name="math_constants"
source-dir="app"
main="main.f90"
-[[test]]
+[[ test ]]
name="runTests"
source-dir="test"
main="main.f90"
@@ -546,12 +546,12 @@ source-dir="src"
[dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
-[[executable]]
+[[ executable ]]
name="math_constants"
source-dir="app"
main="main.f90"
-[[test]]
+[[ test ]]
name="runTests"
source-dir="test"
main="main.f90"
@@ -601,14 +601,14 @@ copyright = "2020 Jane Programmer"
[library]
source-dir="src"
-[[executable]]
+[[ executable ]]
name="math_constants"
source-dir="app"
main="main.f90"
[executable.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
-[[test]]
+[[ test ]]
name="runTests"
source-dir="test"
main="main.f90"
@@ -633,12 +633,12 @@ source-dir="src"
[dev-dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
-[[executable]]
+[[ executable ]]
name="math_constants"
source-dir="app"
main="main.f90"
-[[test]]
+[[ test ]]
name="runTests"
source-dir="test"
main="main.f90"
diff --git a/doc/Contributing.md b/doc/Contributing.md
new file mode 100644
index 0000000..5a7fccc
--- /dev/null
+++ b/doc/Contributing.md
@@ -0,0 +1,5 @@
+---
+title: Contributing Guidelines
+---
+
+{!CONTRIBUTING.md!}
diff --git a/doc/License.md b/doc/License.md
new file mode 100644
index 0000000..6a51b7d
--- /dev/null
+++ b/doc/License.md
@@ -0,0 +1,5 @@
+---
+title: License
+---
+
+{!LICENSE!}
diff --git a/doc/Manifest.md b/doc/Manifest.md
new file mode 100644
index 0000000..1ad48ce
--- /dev/null
+++ b/doc/Manifest.md
@@ -0,0 +1,6 @@
+---
+title: Manifest reference
+---
+
+{!manifest-reference.md!}
+
diff --git a/doc/Packaging.md b/doc/Packaging.md
new file mode 100644
index 0000000..46a4c1b
--- /dev/null
+++ b/doc/Packaging.md
@@ -0,0 +1,5 @@
+---
+title: Packaging with fpm
+---
+
+{!PACKAGING.md!}
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..2db3638
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,3 @@
+---
+title: Packaging and contributing
+---
diff --git a/doc/media/favicon.ico b/doc/media/favicon.ico
new file mode 100644
index 0000000..a360390
--- /dev/null
+++ b/doc/media/favicon.ico
Binary files differ
diff --git a/docs.md b/docs.md
new file mode 100644
index 0000000..800cfab
--- /dev/null
+++ b/docs.md
@@ -0,0 +1,32 @@
+---
+project: Fortran-lang/fpm
+summary: Fortran Package Manager
+project_github: https://github.com/fortran-lang/fpm
+project_download: https://github.com/fortran-lang/fpm/archive/master.zip
+author: fortran-lang/fpm contributors
+author_pic: https://fortran-lang.org/assets/img/fortran_logo_512x512.png
+author_email: fortran-lang@groups.io
+github: https://github.com/fortran-lang
+twitter: https://twitter.com/fortranlang
+website: https://fortran-lang.org
+src_dir: ./fpm/src
+output_dir: ./fpm-doc
+page_dir: ./doc
+media_dir: ./doc/media
+exclude_dir: ./bootstrap
+ ./archive
+ ./test
+display: public
+ protected
+source: true
+proc_internals: true
+sort: permission-alpha
+favicon: doc/media/favicon.ico
+print_creation_date: true
+extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
+creation_date: %Y-%m-%d %H:%M %z
+md_extensions: markdown.extensions.toc
+ markdown.extensions.smarty
+---
+
+[TOC]
diff --git a/fpm/src/fpm.f90 b/fpm/src/fpm.f90
index 5ddc6c5..01f3150 100644
--- a/fpm/src/fpm.f90
+++ b/fpm/src/fpm.f90
@@ -321,7 +321,7 @@ logical :: list
stop
endif
else
- !*! expand names, duplicates are a problem??
+ ! expand names, duplicates are a problem??
allocate(foundit(size(settings%name)))
foundit=.false.
FINDIT: do i=1,size(package%executable)
@@ -341,10 +341,10 @@ logical :: list
if(allocated(foundit))deallocate(foundit)
endif
do i=1,size(newwords)
- !*! list is a new option for use with xargs, to move files to production area, valgrind, gdb, ls -l, ....
- !*! maybe add as --mask and could do --mask 'echo %xx' or --mask 'cp %XX /usr/local/bin/' an so on
- !*! default if blank would be filename uptodate|needs|updated|doesnotexist creation_date, ...
- !*! or maybe just list filenames so can pipe through xargs, and so on
+ ! list is a new option for use with xargs, to move files to production area, valgrind, gdb, ls -l, ....
+ ! maybe add as --mask and could do --mask 'echo %xx' or --mask 'cp %XX /usr/local/bin/' an so on
+ ! default if blank would be filename uptodate|needs|updated|doesnotexist creation_date, ...
+ ! or maybe just list filenames so can pipe through xargs, and so on
if(settings%list)then
write(stderr,'(*(g0,1x))')'fpm::run<INFO>:executable expected at',newwords(i),&
& merge('exists ','does not exist',exists(newwords(i)))
@@ -403,7 +403,7 @@ logical :: list
stop
endif
else
- !*! expand names, duplicates are a problem??
+ ! expand names, duplicates are a problem??
allocate(foundit(size(settings%name)))
foundit=.false.
FINDIT: do i=1,size(package%test)
@@ -423,10 +423,10 @@ logical :: list
if(allocated(foundit))deallocate(foundit)
endif
do i=1,size(newwords)
- !*! list is a new option for use with xargs, to move files to production area, valgrind, gdb, ls -l, ....
- !*! maybe add as --mask and could do --mask 'echo %xx' or --mask 'cp %XX /usr/local/bin/' an so on
- !*! default if blank would be filename uptodate|needs|updated|doesnotexist creation_date, ...
- !*! or maybe just list filenames so can pipe through xargs, and so on
+ ! list is a new option for use with xargs, to move files to production area, valgrind, gdb, ls -l, ....
+ ! maybe add as --mask and could do --mask 'echo %xx' or --mask 'cp %XX /usr/local/bin/' an so on
+ ! default if blank would be filename uptodate|needs|updated|doesnotexist creation_date, ...
+ ! or maybe just list filenames so can pipe through xargs, and so on
if(settings%list)then
write(stderr,'(*(g0,1x))')'fpm::run<INFO>:test expected at',newwords(i),&
& merge('exists ','does not exist',exists(newwords(i)))
diff --git a/fpm/src/fpm/cmd/new.f90 b/fpm/src/fpm/cmd/new.f90
index 91145d8..04cd7d5 100644
--- a/fpm/src/fpm/cmd/new.f90
+++ b/fpm/src/fpm/cmd/new.f90
@@ -38,8 +38,8 @@ character(len=8) :: date
! change to new directory as a test. System dependent potentially
call run('cd '//settings%name)
- !*! NOTE: need some system routines to handle filenames like "."
- !*! like realpath() or getcwd().
+ ! NOTE: need some system routines to handle filenames like "."
+ ! like realpath() or getcwd().
bname=basename(settings%name)
! create NAME/.gitignore file
diff --git a/fpm/src/fpm/manifest.f90 b/fpm/src/fpm/manifest.f90
index d3e47de..9d2e793 100644
--- a/fpm/src/fpm/manifest.f90
+++ b/fpm/src/fpm/manifest.f90
@@ -1,11 +1,11 @@
!> Package configuration data.
-!
-! This module provides the necessary procedure to translate a TOML document
-! to the corresponding Fortran type, while verifying it with respect to
-! its schema.
-!
-! Additionally, the required data types for users of this module are reexported
-! to hide the actual implementation details.
+!>
+!> This module provides the necessary procedure to translate a TOML document
+!> to the corresponding Fortran type, while verifying it with respect to
+!> its schema.
+!>
+!> Additionally, the required data types for users of this module are reexported
+!> to hide the actual implementation details.
module fpm_manifest
use fpm_manifest_build_config, only: build_config_t
use fpm_manifest_executable, only : executable_t
diff --git a/fpm/src/fpm/manifest/build_config.f90 b/fpm/src/fpm/manifest/build_config.f90
index 069c3e0..0509915 100644
--- a/fpm/src/fpm/manifest/build_config.f90
+++ b/fpm/src/fpm/manifest/build_config.f90
@@ -1,12 +1,12 @@
!> Implementation of the build configuration data.
-!
-! A build table can currently have the following fields
-!
-! ```toml
-! [build]
-! auto-executables = <bool>
-! auto-tests = <bool>
-! ```
+!>
+!> A build table can currently have the following fields
+!>
+!>```toml
+!>[build]
+!>auto-executables = bool
+!>auto-tests = bool
+!>```
module fpm_manifest_build_config
use fpm_error, only : error_t, syntax_error, fatal_error
use fpm_toml, only : toml_table, toml_key, toml_stat, get_value
diff --git a/fpm/src/fpm/manifest/dependency.f90 b/fpm/src/fpm/manifest/dependency.f90
index 599d43a..a35beb6 100644
--- a/fpm/src/fpm/manifest/dependency.f90
+++ b/fpm/src/fpm/manifest/dependency.f90
@@ -1,27 +1,27 @@
!> Implementation of the meta data for dependencies.
-!
-! A dependency table can currently have the following fields
-!
-! ```toml
-! [dependencies]
-! "dep1" = { git = "url" }
-! "dep2" = { git = "url", branch = "name" }
-! "dep3" = { git = "url", tag = "name" }
-! "dep4" = { git = "url", rev = "sha1" }
-! "dep0" = { path = "path" }
-! ```
-!
-! To reduce the amount of boilerplate code this module provides two constructors
-! for dependency types, one basic for an actual dependency (inline) table
-! and another to collect all dependency objects from a dependencies table,
-! which is handling the allocation of the objects and is forwarding the
-! individual dependency tables to their respective constructors.
-! The usual entry point should be the constructor for the super table.
-!
-! This objects contains a target to retrieve required `fpm` projects to
-! build the target declaring the dependency.
-! Resolving a dependency will result in obtaining a new package configuration
-! data for the respective project.
+!>
+!> A dependency table can currently have the following fields
+!>
+!>```toml
+!>[dependencies]
+!>"dep1" = { git = "url" }
+!>"dep2" = { git = "url", branch = "name" }
+!>"dep3" = { git = "url", tag = "name" }
+!>"dep4" = { git = "url", rev = "sha1" }
+!>"dep0" = { path = "path" }
+!>```
+!>
+!> To reduce the amount of boilerplate code this module provides two constructors
+!> for dependency types, one basic for an actual dependency (inline) table
+!> and another to collect all dependency objects from a dependencies table,
+!> which is handling the allocation of the objects and is forwarding the
+!> individual dependency tables to their respective constructors.
+!> The usual entry point should be the constructor for the super table.
+!>
+!> This objects contains a target to retrieve required `fpm` projects to
+!> build the target declaring the dependency.
+!> Resolving a dependency will result in obtaining a new package configuration
+!> data for the respective project.
module fpm_manifest_dependency
use fpm_error, only : error_t, syntax_error
use fpm_git, only : git_target_t, git_target_tag, git_target_branch, &
diff --git a/fpm/src/fpm/manifest/executable.f90 b/fpm/src/fpm/manifest/executable.f90
index 6675519..87d9a8d 100644
--- a/fpm/src/fpm/manifest/executable.f90
+++ b/fpm/src/fpm/manifest/executable.f90
@@ -1,14 +1,14 @@
!> Implementation of the meta data for an executables.
-!
-! An executable table can currently have the following fields
-!
-! ```toml
-! [[executable]]
-! name = "string"
-! source-dir = "path"
-! main = "file"
-! [executable.dependencies]
-! ```
+!>
+!> An executable table can currently have the following fields
+!>
+!>```toml
+!>[[ executable ]]
+!>name = "string"
+!>source-dir = "path"
+!>main = "file"
+!>[executable.dependencies]
+!>```
module fpm_manifest_executable
use fpm_manifest_dependency, only : dependency_t, new_dependencies
use fpm_error, only : error_t, syntax_error
diff --git a/fpm/src/fpm/manifest/library.f90 b/fpm/src/fpm/manifest/library.f90
index 7a79a2a..965e0f8 100644
--- a/fpm/src/fpm/manifest/library.f90
+++ b/fpm/src/fpm/manifest/library.f90
@@ -1,12 +1,12 @@
!> Implementation of the meta data for libraries.
-!
-! A library table can currently have the following fields
-!
-! ```toml
-! [library]
-! source-dir = "path"
-! build-script = "file"
-! ```
+!>
+!> A library table can currently have the following fields
+!>
+!>```toml
+!>[library]
+!>source-dir = "path"
+!>build-script = "file"
+!>```
module fpm_manifest_library
use fpm_error, only : error_t, syntax_error
use fpm_toml, only : toml_table, toml_key, toml_stat, get_value
diff --git a/fpm/src/fpm/manifest/package.f90 b/fpm/src/fpm/manifest/package.f90
index fc04aa8..b55e6d6 100644
--- a/fpm/src/fpm/manifest/package.f90
+++ b/fpm/src/fpm/manifest/package.f90
@@ -1,32 +1,32 @@
!> Define the package data containing the meta data from the configuration file.
-!
-! The package data defines a Fortran type corresponding to the respective
-! TOML document, after creating it from a package file no more interaction
-! with the TOML document is required.
-!
-! Every configuration type provides it custom constructor (prefixed with `new_`)
-! and knows how to deserialize itself from a TOML document.
-! To ensure we find no untracked content in the package file all keywords are
-! checked and possible entries have to be explicitly allowed in the `check`
-! function.
-! If entries are mutally exclusive or interdependent inside the current table
-! the `check` function is required to enforce this schema on the data structure.
-!
-! The package file root allows the following keywords
-!
-! ```toml
-! name = "string"
-! version = "string"
-! license = "string"
-! author = "string"
-! maintainer = "string"
-! copyright = "string
-! [library]
-! [dependencies]
-! [dev-dependencies]
-! [[executable]]
-! [[test]]
-! ```
+!>
+!> The package data defines a Fortran type corresponding to the respective
+!> TOML document, after creating it from a package file no more interaction
+!> with the TOML document is required.
+!>
+!> Every configuration type provides it custom constructor (prefixed with `new_`)
+!> and knows how to deserialize itself from a TOML document.
+!> To ensure we find no untracked content in the package file all keywords are
+!> checked and possible entries have to be explicitly allowed in the `check`
+!> function.
+!> If entries are mutally exclusive or interdependent inside the current table
+!> the `check` function is required to enforce this schema on the data structure.
+!>
+!> The package file root allows the following keywords
+!>
+!>```toml
+!>name = "string"
+!>version = "string"
+!>license = "string"
+!>author = "string"
+!>maintainer = "string"
+!>copyright = "string"
+!>[library]
+!>[dependencies]
+!>[dev-dependencies]
+!>[[ executable ]]
+!>[[ test ]]
+!>```
module fpm_manifest_package
use fpm_manifest_build_config, only: build_config_t, new_build_config
use fpm_manifest_dependency, only : dependency_t, new_dependencies
diff --git a/fpm/src/fpm/manifest/test.f90 b/fpm/src/fpm/manifest/test.f90
index de4c847..c01d51d 100644
--- a/fpm/src/fpm/manifest/test.f90
+++ b/fpm/src/fpm/manifest/test.f90
@@ -1,18 +1,18 @@
!> Implementation of the meta data for a test.
-!
-! The test data structure is effectively a decorated version of an executable
-! and shares most of its properties, except for the defaults and can be
-! handled under most circumstances just like any other executable.
-!
-! A test table can currently have the following fields
-!
-! ```toml
-! [[test]]
-! name = "string"
-! source-dir = "path"
-! main = "file"
-! [test.dependencies]
-! ```
+!>
+!> The test data structure is effectively a decorated version of an executable
+!> and shares most of its properties, except for the defaults and can be
+!> handled under most circumstances just like any other executable.
+!>
+!> A test table can currently have the following fields
+!>
+!>```toml
+!>[[ test ]]
+!>name = "string"
+!>source-dir = "path"
+!>main = "file"
+!>[test.dependencies]
+!>```
module fpm_manifest_test
use fpm_manifest_dependency, only : dependency_t, new_dependencies
use fpm_manifest_executable, only : executable_t
diff --git a/fpm/src/fpm/toml.f90 b/fpm/src/fpm/toml.f90
index e2445c4..ecefdd8 100644
--- a/fpm/src/fpm/toml.f90
+++ b/fpm/src/fpm/toml.f90
@@ -1,16 +1,16 @@
!> Interface to TOML processing library.
-!
-! This module acts as a proxy to the `toml-f` public Fortran API and allows
-! to selectively expose components from the library to `fpm`.
-! The interaction with `toml-f` data types outside of this module should be
-! limited to tables, arrays and key-lists, most of the necessary interactions
-! are implemented in the building interface with the `get_value` and `set_value`
-! procedures.
-!
-! This module allows to implement features necessary for `fpm`, which are
-! not yet available in upstream `toml-f`.
-!
-! For more details on the library used see: https://github.com/toml-f/toml-f
+!>
+!> This module acts as a proxy to the `toml-f` public Fortran API and allows
+!> to selectively expose components from the library to `fpm`.
+!> The interaction with `toml-f` data types outside of this module should be
+!> limited to tables, arrays and key-lists, most of the necessary interactions
+!> are implemented in the building interface with the `get_value` and `set_value`
+!> procedures.
+!>
+!> This module allows to implement features necessary for `fpm`, which are
+!> not yet available in upstream `toml-f`.
+!>
+!> For more details on the library used see: https://toml-f.github.io/toml-f
module fpm_toml
use fpm_error, only : error_t, fatal_error, file_not_found_error
use tomlf, only : toml_table, toml_array, toml_key, toml_stat, get_value, &
diff --git a/manifest-reference.md b/manifest-reference.md
index 5dd038d..5f0227a 100644
--- a/manifest-reference.md
+++ b/manifest-reference.md
@@ -231,12 +231,12 @@ See [specifying dependencies](#specifying-dependencies) for more details.
*Example:*
```toml
-[[executable]]
+[[ executable ]]
name = "app-name"
source-dir = "prog"
main = "program.f90"
-[[executable]]
+[[ executable ]]
name = "app-tool"
[executable.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
@@ -270,12 +270,12 @@ See [specifying dependencies](#specifying-dependencies) for more details.
*Example:*
```toml
-[[test]]
+[[ test ]]
name = "test-name"
source-dir = "testing"
main = "tester.F90"
-[[test]]
+[[ test ]]
name = "tester"
[test.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }