diff --git a/.github/workflows/doc-deployment.yml b/.github/workflows/doc-deployment.yml new file mode 100644 index 000000000..0e098234c --- /dev/null +++ b/.github/workflows/doc-deployment.yml @@ -0,0 +1,60 @@ +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" + +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: Build Docs + run: | + git fetch --all --tags + ford -r $(git describe --always) --debug API-doc-FORD-file.md + zip -vr API-docs.zip API-doc/ -x "*.DS_Store" + - name: Upload Documentation + uses: actions/upload-artifact@v2 + with: + name: FORD-API-docs + path: ./API-docs.zip + - 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' && ( startsWith( github.ref, 'refs/tags/' ) || github.ref == 'refs/heads/master' ) + with: + deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} + external_repository: fortran-lang/stdlib-docs + publish_dir: ./API-doc + publish_branch: master + allow_empty_commit: true + force_orphan: false + user_name: ${{ github.actor }} + commit_message: "From https://github.com/${{ github.repository }}/commit/${{ github.sha }} ${{ github.ref }}" diff --git a/.gitignore b/.gitignore index 8a63b480c..d6e779c07 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,9 @@ build/ +# FORD generated documentation +# !WARNING! This folder gets deleted and overwritten +API-doc/ + # Prerequisites *.d diff --git a/API-doc-FORD-file.md b/API-doc-FORD-file.md new file mode 100644 index 000000000..3548b6366 --- /dev/null +++ b/API-doc-FORD-file.md @@ -0,0 +1,58 @@ +--- +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=4 +preprocessor: fypp +display: public + protected + private +source: true +proc_internals: true +md_extensions: markdown.extensions.toc +graph: true +graph_maxnodes: 200 +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 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 diff --git a/doc/API.md b/doc/API.md index b8e138eb7..6a8e8c33f 100644 --- a/doc/API.md +++ b/doc/API.md @@ -1,3 +1,7 @@ +--- +title: Fortran stdlib API +--- + # Fortran stdlib API -TODO +@todo expand or remove diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..52f960f3d --- /dev/null +++ b/doc/index.md @@ -0,0 +1,3 @@ +--- +title: Specs, examples & user docs +--- diff --git a/doc/media/favicon.ico b/doc/media/favicon.ico new file mode 100644 index 000000000..a3603903a Binary files /dev/null and b/doc/media/favicon.ico differ diff --git a/doc/specs/index.md b/doc/specs/index.md new file mode 100644 index 000000000..87ed1ad8a --- /dev/null +++ b/doc/specs/index.md @@ -0,0 +1,5 @@ +--- +title: specs +--- + +@todo Explain what these are, how to write them, why they're needed, etc. diff --git a/src/stdlib_experimental_error.md b/doc/specs/stdlib_experimental_error.md similarity index 94% rename from src/stdlib_experimental_error.md rename to doc/specs/stdlib_experimental_error.md index d6c8ca9ae..67ab84bed 100644 --- a/src/stdlib_experimental_error.md +++ b/doc/specs/stdlib_experimental_error.md @@ -1,8 +1,10 @@ -# Catching and handling errors +--- +title: experimental_error +--- -* [`check` - Checks the value of a logical condition](#check---checks-the-value-of-a-logical-condition) -* [`error_stop` - aborts the program](#error_stop---aborts-the-program) +# Catching and handling errors +[TOC] ## `check` - Checks the value of a logical condition diff --git a/src/stdlib_experimental_io.md b/doc/specs/stdlib_experimental_io.md similarity index 93% rename from src/stdlib_experimental_io.md rename to doc/specs/stdlib_experimental_io.md index 7057a31c7..b600241fa 100644 --- a/src/stdlib_experimental_io.md +++ b/doc/specs/stdlib_experimental_io.md @@ -1,8 +1,10 @@ +--- +title: experimental_IO +--- + # IO -* [`loadtxt` - load a 2D array from a text file](#loadtxt---load-a-2d-array-from-a-text-file) -* [`open` - open a file](#open---open-a-file) -* [`savetxt` - save a 2D array into a text file](#savetxt---save-a-2d-array-into-a-text-file) +[TOC] ## `loadtxt` - load a 2D array from a text file diff --git a/src/stdlib_experimental_linalg.md b/doc/specs/stdlib_experimental_linalg.md similarity index 92% rename from src/stdlib_experimental_linalg.md rename to doc/specs/stdlib_experimental_linalg.md index c59e5020d..de5ff8684 100644 --- a/src/stdlib_experimental_linalg.md +++ b/doc/specs/stdlib_experimental_linalg.md @@ -1,8 +1,10 @@ +--- +title: experimental_linalg +--- + # Linear Algebra -* [`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) -* [`eye` - Construct the identity matrix](#eye---construct-the-identity-matrix) -* [`trace` - Trace of a matrix](#trace---trace-of-a-matrix) +[TOC] ## `diag` - Create a diagonal array or extract the diagonal elements of an array diff --git a/src/stdlib_experimental_optval.md b/doc/specs/stdlib_experimental_optval.md similarity index 90% rename from src/stdlib_experimental_optval.md rename to doc/specs/stdlib_experimental_optval.md index 4e74ddc6c..4a86ff932 100644 --- a/src/stdlib_experimental_optval.md +++ b/doc/specs/stdlib_experimental_optval.md @@ -1,6 +1,10 @@ +--- +title: experimental_optval +--- + # Default values for optional arguments -* [`optval` - fallback value for optional arguments](#optval---fallback-value-for-optional-arguments) +[TOC] ## `optval` - fallback value for optional arguments diff --git a/src/stdlib_experimental_quadrature.md b/doc/specs/stdlib_experimental_quadrature.md similarity index 88% rename from src/stdlib_experimental_quadrature.md rename to doc/specs/stdlib_experimental_quadrature.md index 8e6a4d8d9..5a1d2b01a 100644 --- a/src/stdlib_experimental_quadrature.md +++ b/doc/specs/stdlib_experimental_quadrature.md @@ -1,9 +1,10 @@ +--- +title: experimental_quadrature +--- + # Numerical integration -* [`trapz` - integrate sampled values using trapezoidal rule](#trapz---integrate-sampled-values-using-trapezoidal-rule) -* [`trapz_weights` - trapezoidal rule weights for given abscissas](#trapz_weights---trapezoidal-rule-weights-for-given-abscissas) -* [`simps` - integrate sampled values using Simpson's rule (to be implemented)](#simps---integrate-sampled-values-using-simpsons-rule-to-be-implemented) -* [`simps_weights` - Simpson's rule weights for given abscissas (to be implemented)](#simps_weights---simpsons-rule-weights-for-given-abscissas-to-be-implemented) +[TOC] ## `trapz` - integrate sampled values using trapezoidal rule diff --git a/src/stdlib_experimental_stats.md b/doc/specs/stdlib_experimental_stats.md similarity index 96% rename from src/stdlib_experimental_stats.md rename to doc/specs/stdlib_experimental_stats.md index 8fe1d763f..62d5cf551 100644 --- a/src/stdlib_experimental_stats.md +++ b/doc/specs/stdlib_experimental_stats.md @@ -1,10 +1,10 @@ -# Descriptive statistics +--- +title: experimental_stats +--- -* [`cov` - covariance of array elements](#cov---covariance-of-array-elements) -* [`mean` - mean of array elements](#mean---mean-of-array-elements) -* [`moment` - central moments of array elements](#moment---central-moments-of-array-elements) -* [`var` - variance of array elements](#var---variance-of-array-elements) +# Descriptive statistics +[TOC] ## `cov` - covariance of array elements