Add automatic documentation for Fortran fpm (#209)

awvwgk · web-flow · commit e034ad418ad8 · 2020-11-10T21:34:04.000+01:00
- 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
diff --git 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
@@ -0,0 +1,5 @@
+---
+title: Contributing Guidelines
+---
+
+{!CONTRIBUTING.md!}
diff --git a/doc/License.md b/doc/License.md
@@ -0,0 +1,5 @@
+---
+title: License
+---
+
+{!LICENSE!}
diff --git a/doc/Manifest.md b/doc/Manifest.md
@@ -0,0 +1,6 @@
+---
+title: Manifest reference
+---
+
+{!manifest-reference.md!}
+
diff --git a/doc/Packaging.md b/doc/Packaging.md
@@ -0,0 +1,5 @@
+---
+title: Packaging with fpm
+---
+
+{!PACKAGING.md!}
diff --git a/doc/index.md b/doc/index.md
@@ -0,0 +1,3 @@
+---
+title: Packaging and contributing
+---
diff --git a/doc/media/favicon.ico b/doc/media/favicon.ico
diff --git a/docs.md 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
@@ -321,7 +321,7 @@ subroutine cmd_run(settings)
             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 @@ subroutine cmd_run(settings)
         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 @@ subroutine cmd_test(settings)
             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 @@ subroutine cmd_test(settings)
         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
@@ -38,8 +38,8 @@ subroutine cmd_new(settings)
 
     ! 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/fpm/src/fpm/toml.f90 b/fpm/src/fpm/toml.f90
diff --git a/manifest-reference.md b/manifest-reference.md

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +title: Contributing Guidelines
 +---
++
 +{!CONTRIBUTING.md!}
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+---`
	`2`	`+title: Packaging and contributing`
	`3`	`+---`