Merge branch 'master' of https://github.com/fortran-lang/stdlib

Author: nshaffer

.gitattributes

@@ -1,6 +1,9 @@
 # Set the default behavior, in case people don't have core.autocrlf set.
 * text=auto
 
+# Override syntax highlighting
+*.fypp linguist-language=fortran
+
 # Explicitly declare text files you want to always be normalized and converted
 # to native line endings on checkout.
 *.c text
@@ -28,4 +31,4 @@ codecov.yml export-ignore
 .github export-ignore
 
 # Perform substitutions when `git export`ing these files
-.VERSION export-subst
+.VERSION export-subst 

.github/workflows/CI.yml

@@ -73,7 +73,7 @@ jobs:
     - name: Test in-tree builds
       if: contains( matrix.gcc_v, '9') # Only test one compiler on each platform
       run: |
-          cmake .
+          cmake -DCMAKE_MAXIMUM_RANK=4 .
           cmake --build .
           cmake --build . --target test
 

.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

.github/workflows/doc-deployment.yml

@@ -0,0 +1,65 @@
+name: Build and Deploy Documents
+
+on: [push, pull_request]
+
+env:
+  LANG: "en_US.UTF-8"
+  LC_ALL: "en_US.UTF-8"
+  HOMEBREW_DISPLAY_INSTALL_TIMES: "ON"
+  HOMEBREW_NO_ANALYTICS: "ON"
+  HOMEBREW_NO_AUTO_UPDATE: "ON"
+  HOMEBREW_NO_BOTTLE_SOURCE_FALLBACK: "ON"
+  HOMEBREW_NO_GITHUB_API: "ON"
+  HOMEBREW_NO_INSTALL_CLEANUP: "ON"
+  PIP_DISABLE_PIP_VERSION_CHECK: "ON"
+  PIP_NO_CLEAN: "ON"
+  PIP_PREFER_BINARY: "ON"
+  TZ: "UTC"
+  FORD_FILE: "API-doc-FORD-file.md"
+
+jobs:
+  Build-API-Docs:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # Full history to get tag and commit info
+      - name: Install Dependencies
+        run: |
+          pip3 install --prefer-binary --no-clean --disable-pip-version-check --progress-bar off lxml fypp
+          brew install -f --force-bottle --keep-tmp ford
+          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 ${MAYBE_SKIP_SEARCH} "${FORD_FILE}"
+      - name: Upload Documentation
+        uses: actions/upload-artifact@v2
+        with:
+          name: FORD-API-docs
+          path: ./API-doc/
+      - name: Broken Link Check
+        uses: technote-space/broken-link-checker-action@v1
+        with:
+          TARGET: file://${{ github.workspace }}/API-doc/index.html
+          RECURSIVE: true
+          ASSIGNEES: ${{ github.actor }}
+      - name: Deploy API Docs
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.event_name == 'push' && github.repository == 'fortran-lang/stdlib' && ( startsWith( github.ref, 'refs/tags/' ) || github.ref == 'refs/heads/master' )
+        with:
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          cname: 'stdlib.fortran-lang.org'
+          external_repository: fortran-lang/stdlib-docs
+          publish_dir: ./API-doc
+          publish_branch: master
+          allow_empty_commit: true
+          force_orphan: false
+          commit_message: "From https://github.com/${{ github.repository }}/commit/${{ github.sha }} ${{ github.ref }}"

.gitignore

@@ -1,5 +1,9 @@
 build/
 
+# FORD generated documentation
+# !WARNING! This folder gets deleted and overwritten
+API-doc/
+
 # Prerequisites
 *.d
 

API-doc-FORD-file.md

@@ -0,0 +1,95 @@
+---
+project: Fortran-lang/stdlib
+summary: A community driven standard library for (modern) Fortran
+src_dir: src
+exclude_dir: src/tests
+output_dir: API-doc
+page_dir: doc
+media_dir: doc/media
+fpp_extensions: fypp
+preprocess: true
+macro: MAXRANK=3
+preprocessor: fypp
+display: public
+         protected
+source: true
+proc_internals: true
+md_extensions: markdown.extensions.toc
+graph: true
+graph_maxnodes: 250
+graph_maxdepth: 5
+coloured_edges: true
+sort: permission-alpha
+extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
+            iso_c_binding:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fC_005fBINDING.html#ISO_005fC_005fBINDING
+print_creation_date: true
+creation_date: %Y-%m-%d %H:%M %z
+project_github: https://github.com/fortran-lang/stdlib
+project_download: https://github.com/fortran-lang/stdlib/archive/master.zip
+project_website: https://stdlib.fortran-lang.org
+favicon: doc/media/favicon.ico
+license: by-sa
+author: fortran-lang/stdlib 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
+dbg: true
+---
+
+[TOC]
+
+@warning This API documentation for the Fortran-lang/stdlib is a work in progress
+
+@note
+Use the navigation bar at the top of the screen to browse modules, procedures, source files, etc.
+The listings near the bottom of the page are incomplete.
+
+Fortran stdlib API Documentation
+================================
+
+This is the main API documentation landing page generated by [FORD].
+The documentation for comment markup in source code, running [FORD] and the [FORD project file] are all maintained on the [FORD wiki].
+
+[FORD]: https://github.com/Fortran-FOSS-Programmers/ford#readme
+[FORD wiki]: https://github.com/Fortran-FOSS-Programmers/ford/wiki
+[FORD project file]: https://github.com/fortran-lang/stdlib/blob/master/API-doc-FORD-file.md
+
+Goals and Motivation
+====================
+
+The Fortran Standard, as published by the ISO (https://wg5-fortran.org/), does
+not have a Standard Library. The goal of this project is to provide a community
+driven and agreed upon *de facto* "standard" library for Fortran, called a
+Fortran Standard Library (`stdlib`). We have a rigorous process how `stdlib` is
+developed as documented in our [Workflow](page/contributing/Workflow.html). `stdlib` is both a
+specification and a reference implementation. We are cooperating with the
+Fortran Standards Committee (e.g., the effort
+[started](https://github.com/j3-fortran/fortran_proposals/issues/104) at the J3
+committee repository) and the plan is to continue working with the Committee in
+the future (such as in the step 5. in the [Workflow](page/contributing/Workflow.html) document), so
+that if the Committee wants to standardize some feature already available in `stdlib`, it would
+base it on `stdlib`'s implementation.
+
+Scope
+=====
+
+The goal of the Fortran Standard Library is to achieve the following general scope:
+
+* Utilities (containers, strings, files, OS/environment integration, unit
+  testing & assertions, logging,  ...)
+* Algorithms (searching and sorting, merging, ...)
+* Mathematics (linear algebra, sparse matrices, special functions, fast Fourier
+  transform, random numbers, statistics, ordinary differential equations,
+  numerical integration, optimization, ...)
+
+Code of Conduct
+===============
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. Please read first [this Code of Conduct](./page/contributing/CodeOfConduct.html)
+
+License
+=======
+
+The `stdlib` source code and related files and documentation are distributed under the [MIT license](page/License.html).

CNAME

@@ -40,6 +40,14 @@ git clone https://github.com/fortran-lang/stdlib
 cd stdlib
 ```
 
+### Requirements
+
+The preprocessor ```fypp``` (https://github.com/aradi/fypp) is needed because metaprogramming is used.
+It can be installed using the command line installer ```pip```.
+```sh
+pip install fypp
+```
+
 ### Build with CMake
 
 ```sh
@@ -58,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)

README.md

@@ -42,8 +42,46 @@ focus on the semantics of the proposed changes rather than style and formatting.
 * Where conventional and appropriate shortening of a word is used then the underscore may be omitted,
   for example `linspace` is preferred over `lin_space`
 
+## 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:  
+  ```
+  real, allocatable :: a(:), b(:,:)
+  ```  
+  instead of:  
+  ```
+  real, dimension(:), allocatable :: a
+  ```  
+  ```
+  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.
+
 ## End <scope> block closing statements
 
 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).

STYLE_GUIDE.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.