Skip to content

Commit 8c47a35

Browse files
zbeekmanzbeekman
authored
Merge pull request fortran-lang#198 from zbeekman/speed-up-doc-builds
Speed up doc builds & improve documentation
2 parents f80498c + 1bb21d9 commit 8c47a35

14 files changed

+171
-47
lines changed

‎.github/workflows/PR-review.yml

+2-1
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

+8-3
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ env:
1515
PIP_NO_CLEAN: "ON"
1616
PIP_PREFER_BINARY: "ON"
1717
TZ: "UTC"
18+
FORD_FILE: "API-doc-FORD-file.md"
1819

1920
jobs:
2021
Build-API-Docs:
@@ -30,16 +31,20 @@ jobs:
3031
type -a ford
3132
ford --version
3233
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"
3339
- name: Build Docs
3440
run: |
3541
git fetch --all --tags
36-
ford -r $(git describe --always) --debug API-doc-FORD-file.md
37-
zip -vr API-docs.zip API-doc/ -x "*.DS_Store"
42+
ford -r $(git describe --always) --debug ${MAYBE_SKIP_SEARCH} "${FORD_FILE}"
3843
- name: Upload Documentation
3944
uses: actions/upload-artifact@v2
4045
with:
4146
name: FORD-API-docs
42-
path: ./API-docs.zip
47+
path: ./API-doc/
4348
- name: Broken Link Check
4449
uses: technote-space/broken-link-checker-action@v1
4550
with:

‎API-doc-FORD-file.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,15 @@ page_dir: doc
88
media_dir: doc/media
99
fpp_extensions: fypp
1010
preprocess: true
11-
macro: MAXRANK=4
11+
macro: MAXRANK=3
1212
preprocessor: fypp
1313
display: public
1414
protected
15-
private
1615
source: true
1716
proc_internals: true
1817
md_extensions: markdown.extensions.toc
1918
graph: true
20-
graph_maxnodes: 200
19+
graph_maxnodes: 250
2120
graph_maxdepth: 5
2221
coloured_edges: true
2322
sort: permission-alpha

‎README.md

+10
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,16 @@ Alternatively, you can build using provided Makefiles:
6666
make -f Makefile.manual
6767
```
6868

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+
6979
## Contributing
7080

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

‎STYLE_GUIDE.md

+26-8
Original file line numberDiff line numberDiff line change
@@ -44,21 +44,21 @@ focus on the semantics of the proposed changes rather than style and formatting.
4444

4545
## Attributes
4646

47+
<!-- ATTENTION! This section includes intentional trailing whitespace to get decent formatting with GFM and Python Markdown. -->
48+
4749
* Always specify `intent` for dummy arguments.
4850
* Don't use `dimension` attribute to declare arrays because it is less verbose.
49-
Use this:
50-
51+
Use this:
5152
```
5253
real, allocatable :: a(:), b(:,:)
53-
```
54-
55-
instead of:
56-
54+
```
55+
instead of:
5756
```
5857
real, dimension(:), allocatable :: a
59-
real, dimension(:,:), allocatable :: b
58+
```
6059
```
61-
60+
real, dimension(:,:), allocatable :: b
61+
```
6262
When defining many arrays of the same dimension, `dimension` can be used as an exception if it makes the code less verbose.
6363
* If the `optional` attribute is used to declare a dummy argument, it should follow the `intent` attribute.
6464

@@ -67,3 +67,21 @@ focus on the semantics of the proposed changes rather than style and formatting.
6767
Fortran allows certain block constructs or scopes to include the name of the program unit in the end statement.
6868
The convention adopted herein is to include procedure names, `module` names and `program` names in the `end` statement,
6969
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

+3-1
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.

‎doc/CodeOfConduct.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Contributor Code of Conduct
3+
---
4+
5+
{!CODE_OF_CONDUCT.md!}

‎doc/License.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Fortran stdlib License (MIT)
3+
---
4+
5+
{!LICENSE!}

‎doc/StyleGuide.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Style Guide
3+
---
4+
5+
@note
6+
This is a living document.
7+
You are welcome to propose changes to this workflow by opening an
8+
[issue](https://github.com/fortran-lang/stdlib/issues).
9+
10+
[TOC]
11+
12+
{!STYLE_GUIDE.md!}

‎doc/Workflow.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Workflow for Contributors
3+
---
4+
5+
@note
6+
This is a living document.
7+
You are welcome to propose changes to this workflow by opening an
8+
[issue](https://github.com/fortran-lang/stdlib/issues).
9+
10+
{!WORKFLOW.md!}

‎doc/index.md

+8
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
11
---
22
title: Specs, examples & user docs
33
---
4+
5+
@warning
6+
This page is currently under construction!
7+
8+
@todo
9+
Improve the title of this FORD "pages" section, and
10+
improve the organization of pages
11+
to separate end-user, high-level documentation and examples from developer documentation and specs.

‎doc/specs/index.md

+32-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,35 @@
11
---
2-
title: specs
2+
title: Specifications (specs)
33
---
44

5-
@todo Explain what these are, how to write them, why they're needed, etc.
5+
# Fortran stdlib Specifications (specs)
6+
7+
This is and index/directory of the specifications (specs) for each new module/feature as described in the
8+
[workflow document](../Workflow.html).
9+
10+
[TOC]
11+
12+
## Experimental Features & Modules
13+
14+
- [error](./stdlib_experimental_error.html)
15+
- Catching and handling errors
16+
- [IO](./stdlib_experimental_io.html)
17+
- Input/output helper & convenience
18+
- [linalg](./stdlib_experimental_linalg.html)
19+
- Linear Algebra
20+
- [optval](./stdlib_experimental_optval.html)
21+
- Fallback value for optional arguments
22+
- [quadrature](./stdlib_experimental_quadrature.html)
23+
- Numerical integration
24+
- [stats](./stdlib_experimental_stats.html)
25+
- Descriptive Statistics
26+
27+
## Missing specs
28+
29+
@todo
30+
Populate this section with a list of missing specs and link to their
31+
[sources on GH](https://github.com/fortran-lang/stdlib/tree/master/src).
32+
33+
## Released/Stable Features & Modules
34+
35+
- (None yet)

‎doc/specs/stdlib_experimental_error.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,16 @@ title: experimental_error
66

77
[TOC]
88

9-
## `check` - Checks the value of a logical condition
9+
## `[[stdlib_experimental_error(module):check(subroutine)]]` - Checks the value of a logical condition
1010

1111
### Description
1212

1313
Checks the value of a logical condition.
1414

1515
### Syntax
1616

17-
`call check(condition, msg, code, warn)`
17+
`call [[check(subroutine)]](condition, msg, code, warn)`
18+
1819

1920
### Arguments
2021

@@ -77,15 +78,15 @@ program demo_check3
7778
end program demo_check3
7879
```
7980

80-
## `error_stop` - aborts the program
81+
## `[[stdlib_experimental_error:error_stop]]` - aborts the program
8182

8283
### Description
8384

8485
Aborts the program with a message and a nonzero exit code.
8586

8687
### Syntax
8788

88-
`call error_stop(msg, code)`
89+
`call [[stdlib_experimental_error(module):error_stop(interface)]](msg, code)`
8990

9091
### Arguments
9192

‎src/stdlib_experimental_error.f90

+43-25
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
module stdlib_experimental_error
2-
!!Provides a support for catching and handling errors
2+
!! Provide support for catching and handling errors ([spec](../page/specs/stdlib_experimental_error.html))
3+
!!
4+
!! __Read the [specification here](../page/specs/stdlib_experimental_error.html).__
35
use, intrinsic :: iso_fortran_env, only: stderr => error_unit
46
use stdlib_experimental_optval, only: optval
57
implicit none
68
private
79

810
interface ! f{08,18}estop.f90
911
module subroutine error_stop(msg, code)
12+
!! Provides a call to `error stop` and allows the user to specify a code and message.
13+
!!
14+
!! __Read the [specification here](..//page/specs/stdlib_experimental_error.html#description_1).__
1015
character(*), intent(in) :: msg
1116
integer, intent(in), optional :: code
1217
end subroutine error_stop
@@ -17,15 +22,44 @@ end subroutine error_stop
1722
contains
1823

1924
subroutine check(condition, msg, code, warn)
25+
!! Checks the value of a logical condition. ([spec](../page/specs/stdlib_experimental_error.html#description))
26+
!!
27+
!! __Read the [specification here](../page/specs/stdlib_experimental_error.html#description).__
28+
!!
29+
!!##### Behavior
30+
!!
31+
!! If `condition == .false.` and:
32+
!!
33+
!! * No other arguments are provided, it stops the program with the default
34+
!! message and exit code `1`;
35+
!! * `msg` is provided, it prints the value of `msg`;
36+
!! * `code` is provided, it stops the program with the given exit code;
37+
!! * `warn` is provided and `.true.`, it doesn't stop the program and prints
38+
!! the message.
39+
!!
40+
!!##### Examples
41+
!!
42+
!!* If `a /= 5`, stops the program with exit code `1`
43+
!! and prints `Check failed.`
44+
!!``` fortran
45+
!! call check(a == 5)
46+
!!```
47+
!!
48+
!!* As above, but prints `a == 5 failed`.
49+
!!``` fortran
50+
!! call check(a == 5, msg='a == 5 failed.')
51+
!!```
52+
!!
53+
!!* As above, but doesn't stop the program.
54+
!!``` fortran
55+
!! call check(a == 5, msg='a == 5 failed.', warn=.true.)
56+
!!```
57+
!!
58+
!!* As example #2, but stops the program with exit code `77`
59+
!!``` fortran
60+
!! call check(a == 5, msg='a == 5 failed.', code=77)
61+
!!```
2062

21-
! Checks the value of a logical condition. If condition == .false. and:
22-
!
23-
! * No other arguments are provided, it stops the program with the default
24-
! message and exit code 1;
25-
! * msg is provided, it prints the value of msg;
26-
! * code is provided, it stops the program with the given exit code;
27-
! * warn is provided and .true., it doesn't stop the program and prints
28-
! * the message.
2963
!
3064
! Arguments
3165
! ---------
@@ -36,22 +70,6 @@ subroutine check(condition, msg, code, warn)
3670
logical, intent(in), optional :: warn
3771
character(*), parameter :: msg_default = 'Check failed.'
3872

39-
! Examples
40-
! --------
41-
!
42-
! ! If a /= 5, stops the program with exit code 1
43-
! ! and prints 'Check failed.'
44-
! call check(a == 5)
45-
!
46-
! ! As above, but prints 'a == 5 failed.'
47-
! call check(a == 5, msg='a == 5 failed.')
48-
!
49-
! ! As above, but doesn't stop the program.
50-
! call check(a == 5, msg='a == 5 failed.', warn=.true.)
51-
!
52-
! ! As example #2, but stops the program with exit code 77
53-
! call check(a == 5, msg='a == 5 failed.', code=77)
54-
5573
if (.not. condition) then
5674
if (optval(warn, .false.)) then
5775
write(stderr,*) optval(msg, msg_default)

0 commit comments

Comments
 (0)