Skip to content

Commit 85f3df4

Browse files
nshaffernshaffer
committed
Merge branch 'master' of https://github.com/fortran-lang/stdlib 
2 parents b2c6264 + ff99e00 commit 85f3df4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+5579
-830
lines changed

‎.gitattributes

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Set the default behavior, in case people don't have core.autocrlf set.
22
* text=auto
33

4+
# Override syntax highlighting
5+
*.fypp linguist-language=fortran
6+
47
# Explicitly declare text files you want to always be normalized and converted
58
# to native line endings on checkout.
69
*.c text
@@ -28,4 +31,4 @@ codecov.yml export-ignore
2831
.github export-ignore
2932

3033
# Perform substitutions when `git export`ing these files
31-
.VERSION export-subst
34+
.VERSION export-subst

‎.github/workflows/CI.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ jobs:
7373
- name: Test in-tree builds
7474
if: contains( matrix.gcc_v, '9') # Only test one compiler on each platform
7575
run: |
76-
cmake .
76+
cmake -DCMAKE_MAXIMUM_RANK=4 .
7777
cmake --build .
7878
cmake --build . --target test
7979

‎.github/workflows/PR-review.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ jobs:
1010
- name: misspell
1111
uses: reviewdog/action-misspell@v1
1212
with:
13-
github_token: ${{ secrets.github_token }}
13+
github_token: ${{ secrets.GITHUB_TOKEN }}
1414
locale: "US"
1515
reporter: github-pr-review
1616
level: warning
17+
ignore: colour

‎.github/workflows/doc-deployment.yml

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Build and Deploy Documents
2+
3+
on: [push, pull_request]
4+
5+
env:
6+
LANG: "en_US.UTF-8"
7+
LC_ALL: "en_US.UTF-8"
8+
HOMEBREW_DISPLAY_INSTALL_TIMES: "ON"
9+
HOMEBREW_NO_ANALYTICS: "ON"
10+
HOMEBREW_NO_AUTO_UPDATE: "ON"
11+
HOMEBREW_NO_BOTTLE_SOURCE_FALLBACK: "ON"
12+
HOMEBREW_NO_GITHUB_API: "ON"
13+
HOMEBREW_NO_INSTALL_CLEANUP: "ON"
14+
PIP_DISABLE_PIP_VERSION_CHECK: "ON"
15+
PIP_NO_CLEAN: "ON"
16+
PIP_PREFER_BINARY: "ON"
17+
TZ: "UTC"
18+
FORD_FILE: "API-doc-FORD-file.md"
19+
20+
jobs:
21+
Build-API-Docs:
22+
runs-on: macos-latest
23+
steps:
24+
- uses: actions/checkout@v2
25+
with:
26+
fetch-depth: 0 # Full history to get tag and commit info
27+
- name: Install Dependencies
28+
run: |
29+
pip3 install --prefer-binary --no-clean --disable-pip-version-check --progress-bar off lxml fypp
30+
brew install -f --force-bottle --keep-tmp ford
31+
type -a ford
32+
ford --version
33+
gfortran --version
34+
- name: Skip graph and search unless deploying
35+
if: github.ref != 'refs/heads/master' && ! startsWith( github.ref, 'refs/tags/' )
36+
run: |
37+
sed -i .bak 's/^[[:blank:]]*graph: *[Tt]rue/graph: false/' "${FORD_FILE}"
38+
echo "::set-env name=MAYBE_SKIP_SEARCH::--no-search"
39+
- name: Build Docs
40+
run: |
41+
git fetch --all --tags
42+
ford -r $(git describe --always) --debug ${MAYBE_SKIP_SEARCH} "${FORD_FILE}"
43+
- name: Upload Documentation
44+
uses: actions/upload-artifact@v2
45+
with:
46+
name: FORD-API-docs
47+
path: ./API-doc/
48+
- name: Broken Link Check
49+
uses: technote-space/broken-link-checker-action@v1
50+
with:
51+
TARGET: file://${{ github.workspace }}/API-doc/index.html
52+
RECURSIVE: true
53+
ASSIGNEES: ${{ github.actor }}
54+
- name: Deploy API Docs
55+
uses: peaceiris/actions-gh-pages@v3
56+
if: github.event_name == 'push' && github.repository == 'fortran-lang/stdlib' && ( startsWith( github.ref, 'refs/tags/' ) || github.ref == 'refs/heads/master' )
57+
with:
58+
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
59+
cname: 'stdlib.fortran-lang.org'
60+
external_repository: fortran-lang/stdlib-docs
61+
publish_dir: ./API-doc
62+
publish_branch: master
63+
allow_empty_commit: true
64+
force_orphan: false
65+
commit_message: "From https://github.com/${{ github.repository }}/commit/${{ github.sha }} ${{ github.ref }}"

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
build/
22

3+
# FORD generated documentation
4+
# !WARNING! This folder gets deleted and overwritten
5+
API-doc/
6+
37
# Prerequisites
48
*.d
59

‎API-doc-FORD-file.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
project: Fortran-lang/stdlib
3+
summary: A community driven standard library for (modern) Fortran
4+
src_dir: src
5+
exclude_dir: src/tests
6+
output_dir: API-doc
7+
page_dir: doc
8+
media_dir: doc/media
9+
fpp_extensions: fypp
10+
preprocess: true
11+
macro: MAXRANK=3
12+
preprocessor: fypp
13+
display: public
14+
protected
15+
source: true
16+
proc_internals: true
17+
md_extensions: markdown.extensions.toc
18+
graph: true
19+
graph_maxnodes: 250
20+
graph_maxdepth: 5
21+
coloured_edges: true
22+
sort: permission-alpha
23+
extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
24+
iso_c_binding:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fC_005fBINDING.html#ISO_005fC_005fBINDING
25+
print_creation_date: true
26+
creation_date: %Y-%m-%d %H:%M %z
27+
project_github: https://github.com/fortran-lang/stdlib
28+
project_download: https://github.com/fortran-lang/stdlib/archive/master.zip
29+
project_website: https://stdlib.fortran-lang.org
30+
favicon: doc/media/favicon.ico
31+
license: by-sa
32+
author: fortran-lang/stdlib contributors
33+
author_pic: https://fortran-lang.org/assets/img/fortran_logo_512x512.png
34+
author_email: fortran-lang@groups.io
35+
github: https://github.com/fortran-lang
36+
twitter: https://twitter.com/fortranlang
37+
website: https://fortran-lang.org
38+
dbg: true
39+
---
40+
41+
[TOC]
42+
43+
@warning This API documentation for the Fortran-lang/stdlib is a work in progress
44+
45+
@note
46+
Use the navigation bar at the top of the screen to browse modules, procedures, source files, etc.
47+
The listings near the bottom of the page are incomplete.
48+
49+
Fortran stdlib API Documentation
50+
================================
51+
52+
This is the main API documentation landing page generated by [FORD].
53+
The documentation for comment markup in source code, running [FORD] and the [FORD project file] are all maintained on the [FORD wiki].
54+
55+
[FORD]: https://github.com/Fortran-FOSS-Programmers/ford#readme
56+
[FORD wiki]: https://github.com/Fortran-FOSS-Programmers/ford/wiki
57+
[FORD project file]: https://github.com/fortran-lang/stdlib/blob/master/API-doc-FORD-file.md
58+
59+
Goals and Motivation
60+
====================
61+
62+
The Fortran Standard, as published by the ISO (https://wg5-fortran.org/), does
63+
not have a Standard Library. The goal of this project is to provide a community
64+
driven and agreed upon *de facto* "standard" library for Fortran, called a
65+
Fortran Standard Library (`stdlib`). We have a rigorous process how `stdlib` is
66+
developed as documented in our [Workflow](page/contributing/Workflow.html). `stdlib` is both a
67+
specification and a reference implementation. We are cooperating with the
68+
Fortran Standards Committee (e.g., the effort
69+
[started](https://github.com/j3-fortran/fortran_proposals/issues/104) at the J3
70+
committee repository) and the plan is to continue working with the Committee in
71+
the future (such as in the step 5. in the [Workflow](page/contributing/Workflow.html) document), so
72+
that if the Committee wants to standardize some feature already available in `stdlib`, it would
73+
base it on `stdlib`'s implementation.
74+
75+
Scope
76+
=====
77+
78+
The goal of the Fortran Standard Library is to achieve the following general scope:
79+
80+
* Utilities (containers, strings, files, OS/environment integration, unit
81+
testing & assertions, logging, ...)
82+
* Algorithms (searching and sorting, merging, ...)
83+
* Mathematics (linear algebra, sparse matrices, special functions, fast Fourier
84+
transform, random numbers, statistics, ordinary differential equations,
85+
numerical integration, optimization, ...)
86+
87+
Code of Conduct
88+
===============
89+
90+
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)
91+
92+
License
93+
=======
94+
95+
The `stdlib` source code and related files and documentation are distributed under the [MIT license](page/License.html).

‎CNAME

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,14 @@ git clone https://github.com/fortran-lang/stdlib
4040
cd stdlib
4141
```
4242

43+
### Requirements
44+
45+
The preprocessor ```fypp``` (https://github.com/aradi/fypp) is needed because metaprogramming is used.
46+
It can be installed using the command line installer ```pip```.
47+
```sh
48+
pip install fypp
49+
```
50+
4351
### Build with CMake
4452

4553
```sh
@@ -58,6 +66,16 @@ Alternatively, you can build using provided Makefiles:
5866
make -f Makefile.manual
5967
```
6068

69+
## Documentation
70+
71+
Documentation is a work in progress (see issue #4) but is currently available at https://stdlib.fortran-lang.org.
72+
This includes API documentation automatically generated from static analysis and markup comments in the source files
73+
using the [FORD](https://github.com/Fortran-FOSS-programmers/ford/wiki) tool,
74+
as well as a specification document or ["spec"](https://stdlib.fortran-lang.org/page/specs/index.html) for each proposed feature.
75+
76+
Some discussions and prototypes of proposed APIs along with a list of popular open source Fortran projects are available on the
77+
[wiki](https://github.com/fortran-lang/stdlib/wiki).
78+
6179
## Contributing
6280

6381
* [Issues](https://github.com/fortran-lang/stdlib/issues)

‎STYLE_GUIDE.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,46 @@ focus on the semantics of the proposed changes rather than style and formatting.
4242
* Where conventional and appropriate shortening of a word is used then the underscore may be omitted,
4343
for example `linspace` is preferred over `lin_space`
4444

45+
## Attributes
46+
47+
<!-- ATTENTION! This section includes intentional trailing whitespace to get decent formatting with GFM and Python Markdown. -->
48+
49+
* Always specify `intent` for dummy arguments.
50+
* Don't use `dimension` attribute to declare arrays because it is less verbose.
51+
Use this:
52+
```
53+
real, allocatable :: a(:), b(:,:)
54+
```
55+
instead of:
56+
```
57+
real, dimension(:), allocatable :: a
58+
```
59+
```
60+
real, dimension(:,:), allocatable :: b
61+
```
62+
When defining many arrays of the same dimension, `dimension` can be used as an exception if it makes the code less verbose.
63+
* If the `optional` attribute is used to declare a dummy argument, it should follow the `intent` attribute.
64+
4565
## End <scope> block closing statements
4666

4767
Fortran allows certain block constructs or scopes to include the name of the program unit in the end statement.
4868
The convention adopted herein is to include procedure names, `module` names and `program` names in the `end` statement,
4969
unless the closing statement can reasonably be expected to be on the same screen or page, within about 25 lines.
70+
71+
## Document public API code with FORD
72+
73+
Documentation strings should be provided for all public and protected entities and their arguments or parameters.
74+
This is currently accomplished using the [FORD tool](https://github.com/Fortran-FOSS-Programmers/ford).
75+
For help writing FORD style documentation please see the [FORD wiki](https://github.com/Fortran-FOSS-Programmers/ford/wiki).
76+
The following two sections are most relevant for contributing new code:
77+
78+
* [Writing Documentation](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Documentation)
79+
* [Documentation Meta Data](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Documentation-Meta-Data)
80+
* [Limitations](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Limitations)
81+
82+
To write the "spec" (specification) for a new proposal, please place it in the
83+
[FORD "pages"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages) directory at
84+
[`doc/specs/`](https://github.com/fortran-lang/stdlib/tree/master/doc/specs).
85+
To get help please see the ["Writing Pages"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages)
86+
and ["Writing Documentation"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Documentation) pages
87+
on the [FORD wiki](https://github.com/Fortran-FOSS-Programmers/ford/wiki).

‎WORKFLOW.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ experienced contributors will help it through all 5 steps.
2828
(`stdlib_experimental_*.f90`). As part of the PR, when submitting a new
2929
public facing API, please provide the initial draft of the specification
3030
document as well as the the initial reference implementation of this
31-
specification. The specification is a document that describes the API and
31+
specification. The
32+
[specification is a document](https://stdlib.fortran-lang.org/page/specs/index.html)
33+
that describes the API and
3234
the functionality, so that anyone can use it to create an implementation
3335
from scratch without looking at `stdlib`. The `stdlib` library then provides
3436
the reference implementation.

0 commit comments

Comments
 (0)