diff options
author | Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> | 2020-11-10 21:34:04 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-11-10 21:34:04 +0100 |
commit | e034ad418ad8da3754b80a9673b7017e9798b2a0 (patch) | |
tree | dd367c479e5b1e7c5e9b43b5b9f2366528709460 | |
parent | d569a89d7d059a5ba914e51d6fd7b32132b33c5e (diff) | |
download | fpm-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.md | 18 | ||||
-rw-r--r-- | doc/Contributing.md | 5 | ||||
-rw-r--r-- | doc/License.md | 5 | ||||
-rw-r--r-- | doc/Manifest.md | 6 | ||||
-rw-r--r-- | doc/Packaging.md | 5 | ||||
-rw-r--r-- | doc/index.md | 3 | ||||
-rw-r--r-- | doc/media/favicon.ico | bin | 0 -> 16958 bytes | |||
-rw-r--r-- | docs.md | 32 | ||||
-rw-r--r-- | fpm/src/fpm.f90 | 20 | ||||
-rw-r--r-- | fpm/src/fpm/cmd/new.f90 | 4 | ||||
-rw-r--r-- | fpm/src/fpm/manifest.f90 | 14 | ||||
-rw-r--r-- | fpm/src/fpm/manifest/build_config.f90 | 16 | ||||
-rw-r--r-- | fpm/src/fpm/manifest/dependency.f90 | 46 | ||||
-rw-r--r-- | fpm/src/fpm/manifest/executable.f90 | 20 | ||||
-rw-r--r-- | fpm/src/fpm/manifest/library.f90 | 16 | ||||
-rw-r--r-- | fpm/src/fpm/manifest/package.f90 | 56 | ||||
-rw-r--r-- | fpm/src/fpm/manifest/test.f90 | 28 | ||||
-rw-r--r-- | fpm/src/fpm/toml.f90 | 24 | ||||
-rw-r--r-- | manifest-reference.md | 8 |
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 Binary files differnew file mode 100644 index 0000000..a360390 --- /dev/null +++ b/doc/media/favicon.ico @@ -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" } |