diff --git a/.github/workflows/PR-review.yml b/.github/workflows/PR-review.yml index db89297fd..06e77ffb4 100644 --- a/.github/workflows/PR-review.yml +++ b/.github/workflows/PR-review.yml @@ -10,7 +10,8 @@ jobs: - name: misspell uses: reviewdog/action-misspell@v1 with: - github_token: ${{ secrets.github_token }} + github_token: ${{ secrets.GITHUB_TOKEN }} locale: "US" reporter: github-pr-review level: warning + ignore: colour diff --git a/.github/workflows/doc-deployment.yml b/.github/workflows/doc-deployment.yml index b3335cd91..d28a563c6 100644 --- a/.github/workflows/doc-deployment.yml +++ b/.github/workflows/doc-deployment.yml @@ -15,6 +15,7 @@ env: PIP_NO_CLEAN: "ON" PIP_PREFER_BINARY: "ON" TZ: "UTC" + FORD_FILE: "API-doc-FORD-file.md" jobs: Build-API-Docs: @@ -30,16 +31,20 @@ jobs: type -a ford ford --version gfortran --version + - name: Skip graph and search unless deploying + if: github.ref != 'refs/heads/master' && ! startsWith( github.ref, 'refs/tags/' ) + run: | + sed -i .bak 's/^[[:blank:]]*graph: *[Tt]rue/graph: false/' "${FORD_FILE}" + echo "::set-env name=MAYBE_SKIP_SEARCH::--no-search" - name: Build Docs run: | git fetch --all --tags - ford -r $(git describe --always) --debug API-doc-FORD-file.md - zip -vr API-docs.zip API-doc/ -x "*.DS_Store" + ford -r $(git describe --always) --debug ${MAYBE_SKIP_SEARCH} "${FORD_FILE}" - name: Upload Documentation uses: actions/upload-artifact@v2 with: name: FORD-API-docs - path: ./API-docs.zip + path: ./API-doc/ - name: Broken Link Check uses: technote-space/broken-link-checker-action@v1 with: diff --git a/API-doc-FORD-file.md b/API-doc-FORD-file.md index dcd054c84..292fa6e8a 100644 --- a/API-doc-FORD-file.md +++ b/API-doc-FORD-file.md @@ -8,16 +8,15 @@ page_dir: doc media_dir: doc/media fpp_extensions: fypp preprocess: true -macro: MAXRANK=4 +macro: MAXRANK=3 preprocessor: fypp display: public protected - private source: true proc_internals: true md_extensions: markdown.extensions.toc graph: true -graph_maxnodes: 200 +graph_maxnodes: 250 graph_maxdepth: 5 coloured_edges: true sort: permission-alpha diff --git a/README.md b/README.md index eff8e3eed..90b3451ae 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,16 @@ Alternatively, you can build using provided Makefiles: make -f Makefile.manual ``` +## Documentation + +Documentation is a work in progress (see issue #4) but is currently available at https://stdlib.fortran-lang.org. +This includes API documentation automatically generated from static analysis and markup comments in the source files +using the [FORD](https://github.com/Fortran-FOSS-programmers/ford/wiki) tool, +as well as a specification document or ["spec"](https://stdlib.fortran-lang.org/page/specs/index.html) for each proposed feature. + +Some discussions and prototypes of proposed APIs along with a list of popular open source Fortran projects are available on the +[wiki](https://github.com/fortran-lang/stdlib/wiki). + ## Contributing * [Issues](https://github.com/fortran-lang/stdlib/issues) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 35b3930a6..247b5ea50 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -44,21 +44,21 @@ focus on the semantics of the proposed changes rather than style and formatting. ## Attributes + + * Always specify `intent` for dummy arguments. * Don't use `dimension` attribute to declare arrays because it is less verbose. - Use this: - + Use this: ``` real, allocatable :: a(:), b(:,:) - ``` - - instead of: - + ``` + instead of: ``` real, dimension(:), allocatable :: a - real, dimension(:,:), allocatable :: b + ``` ``` - + real, dimension(:,:), allocatable :: b + ``` When defining many arrays of the same dimension, `dimension` can be used as an exception if it makes the code less verbose. * If the `optional` attribute is used to declare a dummy argument, it should follow the `intent` attribute. @@ -67,3 +67,21 @@ focus on the semantics of the proposed changes rather than style and formatting. Fortran allows certain block constructs or scopes to include the name of the program unit in the end statement. The convention adopted herein is to include procedure names, `module` names and `program` names in the `end` statement, unless the closing statement can reasonably be expected to be on the same screen or page, within about 25 lines. + +## Document public API code with FORD + +Documentation strings should be provided for all public and protected entities and their arguments or parameters. +This is currently accomplished using the [FORD tool](https://github.com/Fortran-FOSS-Programmers/ford). +For help writing FORD style documentation please see the [FORD wiki](https://github.com/Fortran-FOSS-Programmers/ford/wiki). +The following two sections are most relevant for contributing new code: + +* [Writing Documentation](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Documentation) +* [Documentation Meta Data](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Documentation-Meta-Data) +* [Limitations](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Limitations) + +To write the "spec" (specification) for a new proposal, please place it in the +[FORD "pages"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages) directory at +[`doc/specs/`](https://github.com/fortran-lang/stdlib/tree/master/doc/specs). +To get help please see the ["Writing Pages"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages) +and ["Writing Documentation"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Documentation) pages +on the [FORD wiki](https://github.com/Fortran-FOSS-Programmers/ford/wiki). diff --git a/WORKFLOW.md b/WORKFLOW.md index b2ddb233e..4cc391f93 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -28,7 +28,9 @@ experienced contributors will help it through all 5 steps. (`stdlib_experimental_*.f90`). As part of the PR, when submitting a new public facing API, please provide the initial draft of the specification document as well as the the initial reference implementation of this - specification. The specification is a document that describes the API and + specification. The + [specification is a document](https://stdlib.fortran-lang.org/page/specs/index.html) + that describes the API and the functionality, so that anyone can use it to create an implementation from scratch without looking at `stdlib`. The `stdlib` library then provides the reference implementation. diff --git a/doc/CodeOfConduct.md b/doc/CodeOfConduct.md new file mode 100644 index 000000000..df4a90160 --- /dev/null +++ b/doc/CodeOfConduct.md @@ -0,0 +1,5 @@ +--- +title: Contributor Code of Conduct +--- + +{!CODE_OF_CONDUCT.md!} diff --git a/doc/License.md b/doc/License.md new file mode 100644 index 000000000..a55e82126 --- /dev/null +++ b/doc/License.md @@ -0,0 +1,5 @@ +--- +title: Fortran stdlib License (MIT) +--- + +{!LICENSE!} diff --git a/doc/StyleGuide.md b/doc/StyleGuide.md new file mode 100644 index 000000000..e67b3af07 --- /dev/null +++ b/doc/StyleGuide.md @@ -0,0 +1,12 @@ +--- +title: Style Guide +--- + +@note +This is a living document. +You are welcome to propose changes to this workflow by opening an +[issue](https://github.com/fortran-lang/stdlib/issues). + +[TOC] + +{!STYLE_GUIDE.md!} diff --git a/doc/Workflow.md b/doc/Workflow.md new file mode 100644 index 000000000..23350c149 --- /dev/null +++ b/doc/Workflow.md @@ -0,0 +1,10 @@ +--- +title: Workflow for Contributors +--- + +@note +This is a living document. +You are welcome to propose changes to this workflow by opening an +[issue](https://github.com/fortran-lang/stdlib/issues). + +{!WORKFLOW.md!} diff --git a/doc/index.md b/doc/index.md index 52f960f3d..788499305 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,3 +1,11 @@ --- title: Specs, examples & user docs --- + +@warning +This page is currently under construction! + +@todo +Improve the title of this FORD "pages" section, and +improve the organization of pages +to separate end-user, high-level documentation and examples from developer documentation and specs. diff --git a/doc/specs/index.md b/doc/specs/index.md index 87ed1ad8a..7de59cd5c 100644 --- a/doc/specs/index.md +++ b/doc/specs/index.md @@ -1,5 +1,35 @@ --- -title: specs +title: Specifications (specs) --- -@todo Explain what these are, how to write them, why they're needed, etc. +# Fortran stdlib Specifications (specs) + +This is and index/directory of the specifications (specs) for each new module/feature as described in the +[workflow document](../Workflow.html). + +[TOC] + +## Experimental Features & Modules + + - [error](./stdlib_experimental_error.html) + - Catching and handling errors + - [IO](./stdlib_experimental_io.html) + - Input/output helper & convenience + - [linalg](./stdlib_experimental_linalg.html) + - Linear Algebra + - [optval](./stdlib_experimental_optval.html) + - Fallback value for optional arguments + - [quadrature](./stdlib_experimental_quadrature.html) + - Numerical integration + - [stats](./stdlib_experimental_stats.html) + - Descriptive Statistics + +## Missing specs + +@todo +Populate this section with a list of missing specs and link to their +[sources on GH](https://github.com/fortran-lang/stdlib/tree/master/src). + +## Released/Stable Features & Modules + + - (None yet) diff --git a/doc/specs/stdlib_experimental_error.md b/doc/specs/stdlib_experimental_error.md index 67ab84bed..17b5e2072 100644 --- a/doc/specs/stdlib_experimental_error.md +++ b/doc/specs/stdlib_experimental_error.md @@ -6,7 +6,7 @@ title: experimental_error [TOC] -## `check` - Checks the value of a logical condition +## `[[stdlib_experimental_error(module):check(subroutine)]]` - Checks the value of a logical condition ### Description @@ -14,7 +14,8 @@ Checks the value of a logical condition. ### Syntax -`call check(condition, msg, code, warn)` +`call [[check(subroutine)]](condition, msg, code, warn)` + ### Arguments @@ -77,7 +78,7 @@ program demo_check3 end program demo_check3 ``` -## `error_stop` - aborts the program +## `[[stdlib_experimental_error:error_stop]]` - aborts the program ### Description @@ -85,7 +86,7 @@ Aborts the program with a message and a nonzero exit code. ### Syntax -`call error_stop(msg, code)` +`call [[stdlib_experimental_error(module):error_stop(interface)]](msg, code)` ### Arguments diff --git a/src/stdlib_experimental_error.f90 b/src/stdlib_experimental_error.f90 index 07a92fe2e..c731fd35c 100644 --- a/src/stdlib_experimental_error.f90 +++ b/src/stdlib_experimental_error.f90 @@ -1,5 +1,7 @@ module stdlib_experimental_error - !!Provides a support for catching and handling errors + !! Provide support for catching and handling errors ([spec](../page/specs/stdlib_experimental_error.html)) + !! + !! __Read the [specification here](../page/specs/stdlib_experimental_error.html).__ use, intrinsic :: iso_fortran_env, only: stderr => error_unit use stdlib_experimental_optval, only: optval implicit none @@ -7,6 +9,9 @@ module stdlib_experimental_error interface ! f{08,18}estop.f90 module subroutine error_stop(msg, code) + !! Provides a call to `error stop` and allows the user to specify a code and message. + !! + !! __Read the [specification here](..//page/specs/stdlib_experimental_error.html#description_1).__ character(*), intent(in) :: msg integer, intent(in), optional :: code end subroutine error_stop @@ -17,15 +22,44 @@ end subroutine error_stop contains subroutine check(condition, msg, code, warn) + !! Checks the value of a logical condition. ([spec](../page/specs/stdlib_experimental_error.html#description)) + !! + !! __Read the [specification here](../page/specs/stdlib_experimental_error.html#description).__ + !! + !!##### Behavior + !! + !! If `condition == .false.` and: + !! + !! * No other arguments are provided, it stops the program with the default + !! message and exit code `1`; + !! * `msg` is provided, it prints the value of `msg`; + !! * `code` is provided, it stops the program with the given exit code; + !! * `warn` is provided and `.true.`, it doesn't stop the program and prints + !! the message. + !! + !!##### Examples + !! + !!* If `a /= 5`, stops the program with exit code `1` + !! and prints `Check failed.` + !!``` fortran + !! call check(a == 5) + !!``` + !! + !!* As above, but prints `a == 5 failed`. + !!``` fortran + !! call check(a == 5, msg='a == 5 failed.') + !!``` + !! + !!* As above, but doesn't stop the program. + !!``` fortran + !! call check(a == 5, msg='a == 5 failed.', warn=.true.) + !!``` + !! + !!* As example #2, but stops the program with exit code `77` + !!``` fortran + !! call check(a == 5, msg='a == 5 failed.', code=77) + !!``` - ! Checks the value of a logical condition. If condition == .false. and: - ! - ! * No other arguments are provided, it stops the program with the default - ! message and exit code 1; - ! * msg is provided, it prints the value of msg; - ! * code is provided, it stops the program with the given exit code; - ! * warn is provided and .true., it doesn't stop the program and prints - ! * the message. ! ! Arguments ! --------- @@ -36,22 +70,6 @@ subroutine check(condition, msg, code, warn) logical, intent(in), optional :: warn character(*), parameter :: msg_default = 'Check failed.' - ! Examples - ! -------- - ! - ! ! If a /= 5, stops the program with exit code 1 - ! ! and prints 'Check failed.' - ! call check(a == 5) - ! - ! ! As above, but prints 'a == 5 failed.' - ! call check(a == 5, msg='a == 5 failed.') - ! - ! ! As above, but doesn't stop the program. - ! call check(a == 5, msg='a == 5 failed.', warn=.true.) - ! - ! ! As example #2, but stops the program with exit code 77 - ! call check(a == 5, msg='a == 5 failed.', code=77) - if (.not. condition) then if (optval(warn, .false.)) then write(stderr,*) optval(msg, msg_default)