Skip to content

Commit ce987d2

Browse files
milancurcicmilancurcic
authored
Merge pull request #183 from zbeekman/zb-documentation
Add automatic API-doc generation & deployment
2 parents 8be4bc0 + bc26bf1 commit ce987d2

13 files changed

+164
-20
lines changed

‎.github/workflows/doc-deployment.yml

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
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+
19+
jobs:
20+
Build-API-Docs:
21+
runs-on: macos-latest
22+
steps:
23+
- uses: actions/checkout@v2
24+
with:
25+
fetch-depth: 0 # Full history to get tag and commit info
26+
- name: Install Dependencies
27+
run: |
28+
pip3 install --prefer-binary --no-clean --disable-pip-version-check --progress-bar off lxml fypp
29+
brew install -f --force-bottle --keep-tmp ford
30+
type -a ford
31+
ford --version
32+
gfortran --version
33+
- name: Build Docs
34+
run: |
35+
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"
38+
- name: Upload Documentation
39+
uses: actions/upload-artifact@v2
40+
with:
41+
name: FORD-API-docs
42+
path: ./API-docs.zip
43+
- name: Broken Link Check
44+
uses: technote-space/broken-link-checker-action@v1
45+
with:
46+
TARGET: file://${{ github.workspace }}/API-doc/index.html
47+
RECURSIVE: true
48+
ASSIGNEES: ${{ github.actor }}
49+
- name: Deploy API Docs
50+
uses: peaceiris/actions-gh-pages@v3
51+
if: github.event_name == 'push' && github.repository == 'fortran-lang/stdlib' && ( startsWith( github.ref, 'refs/tags/' ) || github.ref == 'refs/heads/master' )
52+
with:
53+
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
54+
external_repository: fortran-lang/stdlib-docs
55+
publish_dir: ./API-doc
56+
publish_branch: master
57+
allow_empty_commit: true
58+
force_orphan: false
59+
commit_message: "From https://github.com/${{ github.repository }}/commit/${{ github.sha }} ${{ github.ref }}"

‎.gitignore

+4
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

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
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=4
12+
preprocessor: fypp
13+
display: public
14+
protected
15+
private
16+
source: true
17+
proc_internals: true
18+
md_extensions: markdown.extensions.toc
19+
graph: true
20+
graph_maxnodes: 200
21+
graph_maxdepth: 5
22+
coloured_edges: true
23+
sort: permission-alpha
24+
extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
25+
iso_c_binding:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fC_005fBINDING.html#ISO_005fC_005fBINDING
26+
print_creation_date: true
27+
creation_date: %Y-%m-%d %H:%M %z
28+
project_github: https://github.com/fortran-lang/stdlib
29+
project_download: https://github.com/fortran-lang/stdlib/archive/master.zip
30+
project_website: https://stdlib.fortran-lang.org
31+
favicon: doc/media/favicon.ico
32+
license: by-sa
33+
author: fortran-lang/stdlib contributors
34+
author_pic: https://fortran-lang.org/assets/img/fortran_logo_512x512.png
35+
author_email: [email protected]
36+
github: https://github.com/fortran-lang
37+
twitter: https://twitter.com/fortranlang
38+
website: https://fortran-lang.org
39+
dbg: true
40+
---
41+
42+
[TOC]
43+
44+
@warning This API documentation for the Fortran-lang/stdlib is a work in progress
45+
46+
@note
47+
Use the navigation bar at the top of the screen to browse modules, procedures, source files, etc.
48+
The listings near the bottom of the page are incomplete.
49+
50+
Fortran stdlib API Documentation
51+
================================
52+
53+
This is the main API documentation landing page generated by [FORD].
54+
The documentation for comment markup in source code, running [FORD] and the [FORD project file] are all maintained on the [FORD wiki].
55+
56+
[FORD]: https://github.com/Fortran-FOSS-Programmers/ford#readme
57+
[FORD wiki]: https://github.com/Fortran-FOSS-Programmers/ford/wiki
58+
[FORD project file]: https://github.com/fortran-lang/stdlib/blob/master/API-doc-FORD-file.md

‎doc/API.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
title: Fortran stdlib API
3+
---
4+
15
# Fortran stdlib API
26

3-
TODO
7+
@todo expand or remove

‎doc/index.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
---
2+
title: Specs, examples & user docs
3+
---

‎doc/media/favicon.ico

16.6 KB
Binary file not shown.

‎doc/specs/index.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: specs
3+
---
4+
5+
@todo Explain what these are, how to write them, why they're needed, etc.

‎src/stdlib_experimental_error.md ‎doc/specs/stdlib_experimental_error.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
# Catching and handling errors
1+
---
2+
title: experimental_error
3+
---
24

3-
* [`check` - Checks the value of a logical condition](#check---checks-the-value-of-a-logical-condition)
4-
* [`error_stop` - aborts the program](#error_stop---aborts-the-program)
5+
# Catching and handling errors
56

7+
[TOC]
68

79
## `check` - Checks the value of a logical condition
810

‎src/stdlib_experimental_io.md ‎doc/specs/stdlib_experimental_io.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
---
2+
title: experimental_IO
3+
---
4+
15
# IO
26

3-
* [`loadtxt` - load a 2D array from a text file](#loadtxt---load-a-2d-array-from-a-text-file)
4-
* [`open` - open a file](#open---open-a-file)
5-
* [`savetxt` - save a 2D array into a text file](#savetxt---save-a-2d-array-into-a-text-file)
7+
[TOC]
68

79
## `loadtxt` - load a 2D array from a text file
810

‎src/stdlib_experimental_linalg.md ‎doc/specs/stdlib_experimental_linalg.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
---
2+
title: experimental_linalg
3+
---
4+
15
# Linear Algebra
26

3-
* [`diag` - Create a diagonal array or extract the diagonal elements of an array](#diag---create-a-diagonal-array-or-extract-the-diagonal-elements-of-an-array)
4-
* [`eye` - Construct the identity matrix](#eye---construct-the-identity-matrix)
5-
* [`trace` - Trace of a matrix](#trace---trace-of-a-matrix)
7+
[TOC]
68

79
## `diag` - Create a diagonal array or extract the diagonal elements of an array
810

‎src/stdlib_experimental_optval.md ‎doc/specs/stdlib_experimental_optval.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1+
---
2+
title: experimental_optval
3+
---
4+
15
# Default values for optional arguments
26

3-
* [`optval` - fallback value for optional arguments](#optval---fallback-value-for-optional-arguments)
7+
[TOC]
48

59
## `optval` - fallback value for optional arguments
610

‎src/stdlib_experimental_quadrature.md ‎doc/specs/stdlib_experimental_quadrature.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
1+
---
2+
title: experimental_quadrature
3+
---
4+
15
# Numerical integration
26

3-
* [`trapz` - integrate sampled values using trapezoidal rule](#trapz---integrate-sampled-values-using-trapezoidal-rule)
4-
* [`trapz_weights` - trapezoidal rule weights for given abscissas](#trapz_weights---trapezoidal-rule-weights-for-given-abscissas)
5-
* [`simps` - integrate sampled values using Simpson's rule (to be implemented)](#simps---integrate-sampled-values-using-simpsons-rule-to-be-implemented)
6-
* [`simps_weights` - Simpson's rule weights for given abscissas (to be implemented)](#simps_weights---simpsons-rule-weights-for-given-abscissas-to-be-implemented)
7+
[TOC]
78

89
## `trapz` - integrate sampled values using trapezoidal rule
910

‎src/stdlib_experimental_stats.md ‎doc/specs/stdlib_experimental_stats.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Descriptive statistics
1+
---
2+
title: experimental_stats
3+
---
24

3-
* [`cov` - covariance of array elements](#cov---covariance-of-array-elements)
4-
* [`mean` - mean of array elements](#mean---mean-of-array-elements)
5-
* [`moment` - central moments of array elements](#moment---central-moments-of-array-elements)
6-
* [`var` - variance of array elements](#var---variance-of-array-elements)
5+
# Descriptive statistics
76

7+
[TOC]
88

99
## `cov` - covariance of array elements
1010

0 commit comments

Comments
 (0)