Speed up doc builds & improve documentation

.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
+          reporter: [github-pr-review]
           level: warning
+          ignore: [colour]

.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: ! ( startsWith( github.ref, 'refs/tags/' ) || github.ref == 'refs/heads/master' )
+        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-docs
       - name: Broken Link Check
         uses: technote-space/broken-link-checker-action@v1
         with:

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

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)

STYLE_GUIDE.md

@@ -44,21 +44,21 @@ focus on the semantics of the proposed changes rather than style and formatting.
 
 ## Attributes
 
+<!-- ATTENTION! This section includes intentional trailing whitespace to get decent formatting with GFM and Python Markdown. -->
+
 * 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)
+
+For 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).

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.

doc/CodeOfConduct.md

@@ -0,0 +1,5 @@
+---
+title: Contributor Code of Conduct
+---
+
+{!CODE_OF_CONDUCT.md!}

doc/License.md

@@ -0,0 +1,5 @@
+---
+title: Fortran stdlib License (MIT)
+---
+
+{!LICENSE!}

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!}

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!}

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.

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)

doc/specs/stdlib_experimental_error.md

@@ -6,15 +6,16 @@ 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
 
 Checks the value of a logical condition.
 
 ### Syntax
 
-`call check(condition, msg, code, warn)`
+`call [[check(subroutine)]](condition, msg, code, warn)`
+
 
 ### Arguments
 
@@ -77,15 +78,15 @@ program demo_check3
 end program demo_check3
 ```
 
-## `error_stop` - aborts the program
+## `[[stdlib_experimental_error:error_stop]]` - aborts the program
 
 ### Description
 
 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
 

src/stdlib_experimental_error.f90

@@ -1,12 +1,17 @@
 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
 private
 
 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)