Skip to content

Commit 8c47a35

Browse files
zbeekmanzbeekman
authored
Merge pull request #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

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: 8 additions & 3 deletions
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

Lines changed: 2 additions & 3 deletions
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

Lines changed: 10 additions & 0 deletions
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

Lines changed: 26 additions & 8 deletions
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

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.

‎doc/CodeOfConduct.md

Lines changed: 5 additions & 0 deletions
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

Lines changed: 5 additions & 0 deletions
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

Lines changed: 12 additions & 0 deletions
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

Lines changed: 10 additions & 0 deletions
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!}

0 commit comments

Comments
 (0)