diff --git a/+matmap3d/R3.m b/+matmap3d/R3.m index 832c10a..7291a9f 100644 --- a/+matmap3d/R3.m +++ b/+matmap3d/R3.m @@ -1,6 +1,5 @@ function A = R3(x) -%% R3(x) -% rotation matrix for ECI +%% R3 rotation matrix for ECI A = [cos(x), sin(x), 0; -sin(x), cos(x), 0; 0, 0, 1]; diff --git a/+matmap3d/aer2ecef.m b/+matmap3d/aer2ecef.m index 172a423..776dd94 100644 --- a/+matmap3d/aer2ecef.m +++ b/+matmap3d/aer2ecef.m @@ -1,6 +1,4 @@ -function [x,y,z] = aer2ecef(az, el, slantRange, lat0, lon0, alt0, spheroid, angleUnit) -%% AER2CEF(az, el, slantRange, lat0, lon0, alt0, spheroid, angleUnit) -% convert azimuth, elevation, range to target from observer to ECEF coordinates +%% AER2ECEF convert azimuth, elevation, range to target from observer to ECEF coordinates % %%% Inputs % @@ -14,7 +12,9 @@ %%% outputs % % * x,y,z: Earth Centered Earth Fixed (ECEF) coordinates of test point (meters) -%% sanity checks + +function [x,y,z] = aer2ecef(az, el, slantRange, lat0, lon0, alt0, spheroid, angleUnit) + arguments az {mustBeReal} el {mustBeReal} diff --git a/+matmap3d/aer2eci.m b/+matmap3d/aer2eci.m index 42f94dc..accef64 100644 --- a/+matmap3d/aer2eci.m +++ b/+matmap3d/aer2eci.m @@ -1,6 +1,5 @@ -function [x, y, z] = aer2eci(utc, az, el, rng, lat, lon, alt) -%% aer2eci(utc, az, el, rng, lat, lon, alt) -% convert AER (azimuth, elevation, slant range) to ECI +%% AER2ECI convert AER (azimuth, elevation, slant range) to ECI +% % NOTE: because underlying ecef2eci() is rotation only, error can be order % 1..10% % @@ -11,6 +10,7 @@ % %%% Outputs % * x, y, z: ECI x, y, z +function [x, y, z] = aer2eci(utc, az, el, rng, lat, lon, alt) arguments utc datetime az {mustBeReal} diff --git a/+matmap3d/aer2enu.m b/+matmap3d/aer2enu.m index 3978c48..32f1b4d 100644 --- a/+matmap3d/aer2enu.m +++ b/+matmap3d/aer2enu.m @@ -1,6 +1,4 @@ -function [e, n, u] = aer2enu (az, el, slantRange, angleUnit) -%% aer2enu(az, el, slantRange, angleUnit) -% convert azimuth, elevation, range to ENU coordinates +%% AER2ENU convert azimuth, elevation, range to ENU coordinates % %%% Inputs % * az, el, slantrange: look angles and distance to point under test (degrees, degrees, meters) @@ -10,6 +8,7 @@ % %%% Outputs % * e,n,u: East, North, Up coordinates of test points (meters) +function [e, n, u] = aer2enu (az, el, slantRange, angleUnit) arguments az {mustBeReal} el {mustBeReal} diff --git a/+matmap3d/aer2geodetic.m b/+matmap3d/aer2geodetic.m index 329f339..73096ef 100644 --- a/+matmap3d/aer2geodetic.m +++ b/+matmap3d/aer2geodetic.m @@ -1,6 +1,4 @@ -function [lat1, lon1, alt1] = aer2geodetic(az, el, slantRange, lat0, lon0, alt0, spheroid, angleUnit) -%% aer2geodetic(az, el, slantRange, lat0, lon0, alt0, spheroid, angleUnit) -% convert azimuth, elevation, range of target from observer to geodetic coordiantes +%% aer2geodetic convert azimuth, elevation, range of target from observer to geodetic coordiantes % %%% Inputs % * az, el, slantrange: look angles and distance to point under test (degrees, degrees, meters) @@ -12,6 +10,7 @@ % %%% Outputs % * lat1,lon1,alt1: geodetic coordinates of test points (degrees,degrees,meters) +function [lat1, lon1, alt1] = aer2geodetic(az, el, slantRange, lat0, lon0, alt0, spheroid, angleUnit) arguments az {mustBeReal} el {mustBeReal} diff --git a/+matmap3d/aer2ned.m b/+matmap3d/aer2ned.m index cc64d49..7485332 100644 --- a/+matmap3d/aer2ned.m +++ b/+matmap3d/aer2ned.m @@ -1,6 +1,4 @@ -function [north, east, down] = aer2ned(az, el, slantRange, angleUnit) -%% aer2ned(az, el, slantRange, angleUnit) -% convert azimuth, elevation, range to NED coordinates +%% AER2NED convert azimuth, elevation, range to NED coordinates % %%% Inputs % * az, el, slantrange: look angles and distance to point under test (degrees, degrees, meters) @@ -10,6 +8,7 @@ % %%% Outputs % * north, east, down: coordinates of points (meters) +function [north, east, down] = aer2ned(az, el, slantRange, angleUnit) arguments az {mustBeReal} el {mustBeReal} diff --git a/+matmap3d/ecef2aer.m b/+matmap3d/ecef2aer.m index 97dc5d3..5596005 100644 --- a/+matmap3d/ecef2aer.m +++ b/+matmap3d/ecef2aer.m @@ -1,6 +1,4 @@ -function [az, el, slantRange] = ecef2aer(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) -%% ecef2aer(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) -% convert ECEF of target to azimuth, elevation, slant range from observer +%% ECEF2AER convert ECEF of target to azimuth, elevation, slant range from observer % %%% Inputs % * x,y,z: Earth Centered Earth Fixed (ECEF) coordinates of test point (meters) @@ -12,6 +10,8 @@ % * az, el, slantrange: look angles and distance to point under test (degrees, degrees, meters) % * az: azimuth clockwise from local north % * el: elevation angle above local horizon +function [az, el, slantRange] = ecef2aer(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) + arguments x {mustBeReal} y {mustBeReal} diff --git a/+matmap3d/ecef2eci.m b/+matmap3d/ecef2eci.m index 8b2ba20..7102134 100644 --- a/+matmap3d/ecef2eci.m +++ b/+matmap3d/ecef2eci.m @@ -1,6 +1,4 @@ -function [x,y,z] = ecef2eci(utc, x0, y0, z0) -%% ecef2eci(utc, x0, y0, z0) -% rotate ECEF coordinates to ECI +%% ECEF2ECI rotate ECEF coordinates to ECI % because this doesn't account for nutation, etc. error is often > 1% % %%% Inputs @@ -8,6 +6,8 @@ % utc: time UTC %%% Outputs % * x,y,z: ECI position (meters) + +function [x,y,z] = ecef2eci(utc, x0, y0, z0) arguments utc (:,1) datetime x0 (:,1) {mustBeReal,mustBeEqualSize(utc,x0)} diff --git a/+matmap3d/ecef2enu.m b/+matmap3d/ecef2enu.m index 6c6c623..63a5869 100644 --- a/+matmap3d/ecef2enu.m +++ b/+matmap3d/ecef2enu.m @@ -1,6 +1,5 @@ -function [east, north, up] = ecef2enu(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) -%% ecef2ned(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) -% convert ECEF to NED + +%% ECEF2ENU convert ECEF to ENU % %%% Inputs % * x,y,z: Earth Centered Earth Fixed (ECEF) coordinates of test point (meters) @@ -10,6 +9,8 @@ % %%% outputs % * East, North, Up coordinates of test points (meters) + +function [east, north, up] = ecef2enu(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) arguments x {mustBeReal} y {mustBeReal} diff --git a/+matmap3d/ecef2enuv.m b/+matmap3d/ecef2enuv.m index 1b5f822..a2711f5 100644 --- a/+matmap3d/ecef2enuv.m +++ b/+matmap3d/ecef2enuv.m @@ -1,6 +1,4 @@ -function [e, n, Up] = ecef2enuv(u, v, w, lat0, lon0, angleUnit) -%% ecef2enuv -% convert *vector projection* UVW to ENU +%% ECEF2ENUV convert *vector projection* UVW to ENU % %%% Inputs % * u,v,w: meters @@ -9,6 +7,8 @@ % %%% Outputs % * e,n,Up: East, North, Up vector + +function [e, n, Up] = ecef2enuv(u, v, w, lat0, lon0, angleUnit) arguments u {mustBeReal} v {mustBeReal} diff --git a/+matmap3d/ecef2geodetic.m b/+matmap3d/ecef2geodetic.m index 5cf6928..d440f44 100644 --- a/+matmap3d/ecef2geodetic.m +++ b/+matmap3d/ecef2geodetic.m @@ -1,6 +1,4 @@ -function [lat,lon,alt] = ecef2geodetic(spheroid, x, y, z, angleUnit) -%% ecef2geodetic -% convert ECEF to geodetic coordinates +%% ECEF2GEODETIC convert ECEF to geodetic coordinates % %%% Inputs % * x,y,z: ECEF coordinates of test point(s) (meters) @@ -13,6 +11,8 @@ % based on: % You, Rey-Jer. (2000). Transformation of Cartesian to Geodetic Coordinates without Iterations. % Journal of Surveying Engineering. doi: 10.1061/(ASCE)0733-9453 + +function [lat,lon,alt] = ecef2geodetic(spheroid, x, y, z, angleUnit) arguments spheroid {mustBeScalarOrEmpty} x {mustBeReal} diff --git a/+matmap3d/ecef2ned.m b/+matmap3d/ecef2ned.m index 7f03da2..895aa19 100644 --- a/+matmap3d/ecef2ned.m +++ b/+matmap3d/ecef2ned.m @@ -1,6 +1,4 @@ -function [north, east, down] = ecef2ned(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) -%% ecef2enu -% convert ECEF to ENU +%% ECEF2NED Convert ECEF coordinates to NED % %%% Inputs % * x,y,z: Earth Centered Earth Fixed (ECEF) coordinates of test point (meters) @@ -10,7 +8,7 @@ % %%% outputs % * North,East,Down: coordinates of points (meters) - +function [north, east, down] = ecef2ned(x, y, z, lat0, lon0, alt0, spheroid, angleUnit) arguments x {mustBeReal} y {mustBeReal} diff --git a/+matmap3d/eci2aer.m b/+matmap3d/eci2aer.m index 37c7e8f..c2aea30 100644 --- a/+matmap3d/eci2aer.m +++ b/+matmap3d/eci2aer.m @@ -1,6 +1,4 @@ -function [az, el, rng] = eci2aer(utc, x0, y0, z0, lat, lon, alt) -%% eci2aer(utc, x0, y0, z0, lat, lon, alt) -% convert ECI to AER (azimuth, elevation, slant range) +%% ECI2AER convert ECI to AER (azimuth, elevation, slant range) % % parameters: % utc: datetime UTC @@ -9,6 +7,7 @@ % % outputs: % az,el,rng: Azimuth (degrees), Elevation (degrees), Slant Range (meters) +function [az, el, rng] = eci2aer(utc, x0, y0, z0, lat, lon, alt) arguments utc datetime x0 {mustBeReal} diff --git a/+matmap3d/eci2ecef.m b/+matmap3d/eci2ecef.m index 0e63734..95ccb62 100644 --- a/+matmap3d/eci2ecef.m +++ b/+matmap3d/eci2ecef.m @@ -1,12 +1,11 @@ -function [x,y,z] = eci2ecef(utc, x_eci, y_eci, z_eci) -%% eci2ecef(utc, x_eci, y_eci, z_eci) -% rotate ECI coordinates to ECEF +%% ECI2ECEF rotate ECI coordinates to ECEF % because this doesn't account for nutation, etc. error is often > 1% % % x_eci, y_eci, z_eci: eci position vectors % utc: Matlab datetime UTC % % x,y,z: ECEF position (meters) +function [x,y,z] = eci2ecef(utc, x_eci, y_eci, z_eci) arguments utc (:,1) datetime x_eci (:,1) {mustBeReal,mustBeEqualSize(utc,x_eci)} diff --git a/+matmap3d/enu2aer.m b/+matmap3d/enu2aer.m index ccc73bb..d088a10 100644 --- a/+matmap3d/enu2aer.m +++ b/+matmap3d/enu2aer.m @@ -1,6 +1,4 @@ -function [az, elev, slantRange] = enu2aer(east, north, up, angleUnit) -%% enu2aer -% convert ENU to azimuth, elevation, slant range +%% ENU2AER convert ENU to azimuth, elevation, slant range % %%% Inputs % * e,n,u: East, North, Up coordinates of test points (meters) @@ -10,6 +8,7 @@ % * az, el, slantrange: look angles and distance to point under test (degrees, degrees, meters) % * az: azimuth clockwise from local north % * el: elevation angle above local horizon +function [az, elev, slantRange] = enu2aer(east, north, up, angleUnit) arguments east {mustBeReal} north {mustBeReal} diff --git a/+matmap3d/enu2ecef.m b/+matmap3d/enu2ecef.m index 3bf2284..806c07b 100644 --- a/+matmap3d/enu2ecef.m +++ b/+matmap3d/enu2ecef.m @@ -1,6 +1,4 @@ -function [x, y, z] = enu2ecef(east, north, up, lat0, lon0, alt0, spheroid, angleUnit) -%% enu2ecef -% convert from ENU to ECEF coordiantes +%% ENU2ECEF convert from ENU to ECEF coordiantes % %%% Inputs % * east, north, up: coordinates of test points (meters) @@ -10,6 +8,7 @@ % %%% outputs % * x,y,z: Earth Centered Earth Fixed (ECEF) coordinates of test point (meters) +function [x, y, z] = enu2ecef(east, north, up, lat0, lon0, alt0, spheroid, angleUnit) arguments east {mustBeReal} north {mustBeReal} diff --git a/+matmap3d/enu2ecefv.m b/+matmap3d/enu2ecefv.m index a83d2d3..d8aed8b 100644 --- a/+matmap3d/enu2ecefv.m +++ b/+matmap3d/enu2ecefv.m @@ -1,5 +1,4 @@ -function [u, v, w] = enu2ecefv(east, north, up, lat0, lon0, angleUnit) -%% enu2ecef convert from ENU to ECEF coordinates +%% ENU2ECEFV convert from ENU to ECEF coordinates % %%% Inputs % * e,n,u: East, North, Up coordinates of point(s) (meters) @@ -8,6 +7,8 @@ % %%% outputs % * u,v,w: coordinates of test point(s) (meters) + +function [u, v, w] = enu2ecefv(east, north, up, lat0, lon0, angleUnit) arguments east {mustBeReal} north {mustBeReal} diff --git a/+matmap3d/enu2geodetic.m b/+matmap3d/enu2geodetic.m index e5cc5b5..7e2979c 100644 --- a/+matmap3d/enu2geodetic.m +++ b/+matmap3d/enu2geodetic.m @@ -1,5 +1,4 @@ -function [lat, lon, alt] = enu2geodetic(east, north, up, lat0, lon0, alt0, spheroid, angleUnit) -%% enu2geodetic convert from ENU to geodetic coordinates +%% ENU2GEODETIC convert from ENU to geodetic coordinates % %%% Inputs % * east,north,up: ENU coordinates of point(s) (meters) @@ -9,6 +8,8 @@ % %%% outputs % * lat,lon,alt: geodetic coordinates of test points (degrees,degrees,meters) + +function [lat, lon, alt] = enu2geodetic(east, north, up, lat0, lon0, alt0, spheroid, angleUnit) arguments east {mustBeReal} north {mustBeReal} diff --git a/+matmap3d/enu2uvw.m b/+matmap3d/enu2uvw.m index 7a35f7b..7883e54 100644 --- a/+matmap3d/enu2uvw.m +++ b/+matmap3d/enu2uvw.m @@ -1,6 +1,4 @@ - -function [u,v,w] = enu2uvw(east,north,up,lat0,lon0,angleUnit) -%% enu2uvw convert from ENU to UVW coordinates +%% ENU2UVW convert from ENU to UVW coordinates % %%% Inputs % * e,n,up: East, North, Up coordinates of point(s) (meters) @@ -9,6 +7,7 @@ % %%% outputs % * u,v,w: coordinates of test point(s) (meters) +function [u,v,w] = enu2uvw(east,north,up,lat0,lon0,angleUnit) arguments east {mustBeReal} north {mustBeReal} diff --git a/+matmap3d/geodetic2aer.m b/+matmap3d/geodetic2aer.m index c00870d..b5417fd 100644 --- a/+matmap3d/geodetic2aer.m +++ b/+matmap3d/geodetic2aer.m @@ -1,5 +1,5 @@ -function [az, el, slantRange] = geodetic2aer(lat, lon, alt, lat0, lon0, alt0, spheroid, angleUnit) -%% geodetic2aer + +%% GEODETIC2AER converts geodetic coordinates to azimuth, elevation, slant range % from an observer's perspective, convert target coordinates to azimuth, elevation, slant range. % %%% Inputs @@ -12,6 +12,7 @@ % * az, el, slantrange: look angles and distance to point under test (degrees, degrees, meters) % * az: azimuth clockwise from local north % * el: elevation angle above local horizon +function [az, el, slantRange] = geodetic2aer(lat, lon, alt, lat0, lon0, alt0, spheroid, angleUnit) arguments lat {mustBeReal} lon {mustBeReal} diff --git a/+matmap3d/geodetic2ecef.m b/+matmap3d/geodetic2ecef.m index 75b2182..1ce7955 100644 --- a/+matmap3d/geodetic2ecef.m +++ b/+matmap3d/geodetic2ecef.m @@ -1,6 +1,4 @@ -function [x,y,z] = geodetic2ecef(spheroid, lat, lon, alt, angleUnit) -%% geodetic2ecef -% convert from geodetic to ECEF coordiantes +%% GEODETIC2ECEF convert from geodetic to ECEF coordiantes % %%% Inputs % * lat,lon, alt: ellipsoid geodetic coordinates of point(s) (degrees, degrees, meters) @@ -9,6 +7,7 @@ % %%% outputs % * x,y,z: ECEF coordinates of test point(s) (meters) +function [x,y,z] = geodetic2ecef(spheroid, lat, lon, alt, angleUnit) arguments spheroid {mustBeScalarOrEmpty} lat {mustBeReal} diff --git a/+matmap3d/geodetic2enu.m b/+matmap3d/geodetic2enu.m index 8fdf366..8a2bb6e 100644 --- a/+matmap3d/geodetic2enu.m +++ b/+matmap3d/geodetic2enu.m @@ -1,6 +1,4 @@ -function [east, north, up] = geodetic2enu(lat, lon, alt, lat0, lon0, alt0, spheroid, angleUnit) -%% geodetic2enu -% convert from geodetic to ENU coordinates +%% GEODETIC2ENU convert from geodetic to ENU coordinates % %%% Inputs % * lat,lon, alt: ellipsoid geodetic coordinates of point under test (degrees, degrees, meters) @@ -10,6 +8,7 @@ % %%% outputs % * east,north,up: coordinates of points (meters) +function [east, north, up] = geodetic2enu(lat, lon, alt, lat0, lon0, alt0, spheroid, angleUnit) arguments lat {mustBeReal} lon {mustBeReal} diff --git a/+matmap3d/get_radius_normal.m b/+matmap3d/get_radius_normal.m index 1729d35..5399f17 100644 --- a/+matmap3d/get_radius_normal.m +++ b/+matmap3d/get_radius_normal.m @@ -1,6 +1,4 @@ -function N = get_radius_normal(lat, E) -%% get_radius_normal -% normal along the prime vertical section ellipsoidal radius of curvature +%% GET_RADIUS_NORMAL normal along the prime vertical section ellipsoidal radius of curvature % %%% Inputs % * lat: geodetic latitude in Radians @@ -8,6 +6,7 @@ % %%% Outputs % * N: normal along the prime vertical section ellipsoidal radius of curvature, at a given geodetic latitude. +function N = get_radius_normal(lat, E) arguments lat {mustBeReal} E (1,1) matmap3d.referenceEllipsoid diff --git a/+matmap3d/greenwichsrt.m b/+matmap3d/greenwichsrt.m index 56cda65..d2c011e 100644 --- a/+matmap3d/greenwichsrt.m +++ b/+matmap3d/greenwichsrt.m @@ -1,11 +1,11 @@ -function gst = greenwichsrt(Jdate) -%% greenwichsrt(Jdate) +%% GREENWICHSRT Compute greenwich sidereal time from Julian date % compute greenwich sidereal time from D. Vallado 4th edition % %%% Inputs % Jdate: Julian days from Jan 1, 4713 BCE from juliantime(utc) or juliandate(utc) %%% Outputs % gst: greenwich sidereal time [0, 2pi) +function gst = greenwichsrt(Jdate) arguments Jdate {mustBeReal,mustBeNonnegative} end diff --git a/+matmap3d/lookAtSpheroid.m b/+matmap3d/lookAtSpheroid.m index b9faeb7..571a631 100644 --- a/+matmap3d/lookAtSpheroid.m +++ b/+matmap3d/lookAtSpheroid.m @@ -1,5 +1,3 @@ - -function [lat, lon, d] = lookAtSpheroid(lat0, lon0, h0, az, tilt, spheroid, angleUnit) %% LOOKATSPHEROID % Calculates line-of-sight intersection with Earth (or other ellipsoid) surface from above surface ./ orbit % @@ -18,6 +16,7 @@ % Algorithm based on: % https://medium.com/@stephenhartzell/satellite-line-of-sight-intersection-with-earth-d786b4a6a9b6 % Stephen Hartzell +function [lat, lon, d] = lookAtSpheroid(lat0, lon0, h0, az, tilt, spheroid, angleUnit) arguments lat0 {mustBeReal} lon0 {mustBeReal} diff --git a/+matmap3d/vdist.m b/+matmap3d/vdist.m index c57e560..89364a9 100644 --- a/+matmap3d/vdist.m +++ b/+matmap3d/vdist.m @@ -1,4 +1,3 @@ -function varargout = vdist(lat1,lon1,lat2,lon2) %% VDIST - Using the WGS-84 Earth ellipsoid, compute the distance between two points % % within a few millimeters of accuracy, compute forward @@ -16,6 +15,7 @@ % * lat1 = GEODETIC latitude of first point (degrees) % * lon1 = longitude of first point (degrees) % * lat2, lon2 = second point (degrees) +function varargout = vdist(lat1,lon1,lat2,lon2) % %%% Original algorithm source: % diff --git a/+matmap3d/vreckon.m b/+matmap3d/vreckon.m index 6e956c3..8f79f1b 100644 --- a/+matmap3d/vreckon.m +++ b/+matmap3d/vreckon.m @@ -1,5 +1,4 @@ -function [lat2,lon2,a21] = vreckon(lat1,lon1,s,a12) -% RECKON - Using the WGS-84 Earth ellipsoid, travel a given distance along +% VRECKON - Using the WGS-84 Earth ellipsoid, travel a given distance along % a given azimuth starting at a given initial point, and return % the endpoint within a few millimeters of accuracy, using % Vincenty's algorithm. @@ -46,6 +45,7 @@ % for nearly antipodal points. (A warning is given by VDIST.) % (6) Tested but no warranty. Use at your own risk. % (7) Ver 1.0, Michael Kleder, November 2007 +function [lat2,lon2,a21] = vreckon(lat1,lon1,s,a12) arguments lat1 {mustBeReal} lon1 {mustBeReal} diff --git a/+matmap3d/wgs84Ellipsoid.m b/+matmap3d/wgs84Ellipsoid.m index be113e3..eb22c82 100644 --- a/+matmap3d/wgs84Ellipsoid.m +++ b/+matmap3d/wgs84Ellipsoid.m @@ -1,6 +1,4 @@ -function E = wgs84Ellipsoid(lengthUnit) -%% wgs84Ellipsoid -% generate a WGS84 referenceEllipsoid +%% WGS84ELLIPSOID - generate a WGS84 referenceEllipsoid % %%% Inputs % @@ -9,6 +7,7 @@ %%% Outputs % % * E: referenceEllipsoid +function E = wgs84Ellipsoid(lengthUnit) arguments lengthUnit (1,1) string = "m" end diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..a6bb973 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,58 @@ +# Simple workflow for deploying static content to GitHub Pages +name: Deploy static content to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + + deploy: + + strategy: + matrix: + release: ["latest"] + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - uses: ./.github/workflows/composite-install-matlab + + - name: Run Matlab buildtool + uses: matlab-actions/run-build@v2 + with: + tasks: test publish + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 6eeedc4..8991044 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +docs/ resources/ *.asv *.m~ diff --git a/buildfile.m b/buildfile.m index d57636a..f7bfaae 100644 --- a/buildfile.m +++ b/buildfile.m @@ -47,37 +47,57 @@ function coverageTask(~) generateHTMLReport(format.Result) end + function publishTask(~) -% publish (generate) docs from Matlab project - -% for package code -- assumes no classes and depth == 0 -pkg_name = 'matmap3d'; - -r = codeIssues; -files = r.Files; - -% remove nuisance functions -i = contains(files, [mfilename, "buildfile.m", filesep + "private" + filesep]); -files(i) = []; - -pkg = what(pkg_name); -subs = pkg.packages; - -%% generate docs -cwd = fileparts(mfilename('fullpath')); -docs = fullfile(cwd, "docs"); - -for sub = subs.' - s = sub{1}; - i = contains(files, filesep + "+" + s + filesep); - fs = files(i); - for f = fs.' - [~, name, ext] = fileparts(f); - if ext == ".m" - doc_fn = publish(pkg_name + "." + name, evalCode=false, outputDir=docs, showCode=false); - disp(doc_fn) + % publish (generate) docs from Matlab project + % https://www.mathworks.com/help/matlab/ref/publish.html + % https://www.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html + % + % for package code -- assumes no classes and depth == 1 + pkg_name = "matmap3d"; + tagline = "Geographic Map coordinate transform functions for Matlab"; + + pkg = what("+" + pkg_name); + % "+" avoids picking up cwd of same name + + %% generate docs + cwd = fileparts(mfilename('fullpath')); + docs = fullfile(cwd, "docs"); + readme = fullfile(docs, "index.html"); + + if ~isfolder(docs) + mkdir(docs); + end + + txt = [" " + pkg_name + " API ", ... + "

" + pkg_name + " API

", ... + tagline, ... + "

API Reference

"]; + fid = fopen(readme, 'w'); + fprintf(fid, join(txt, "\n")); + + for sub = pkg.m.' + s = sub{1}; + [~, name] = fileparts(s); + doc_fn = publish(pkg_name + "." + name, evalCode=false, outputDir=docs); + disp(doc_fn) + % inject summary into Readme.md + summary = split(string(help(pkg_name + "." + name)), newline); + words = split(strip(summary(1)), " "); + % purposefully this will error if no docstring + fname = words(1); + if(lower(fname) ~= lower(name)) + error("fname %s does not match name %s", fname, name) end + line = "" + fname + " "; + if(length(words) > 1) + line = line + join(words(2:end)); + end + fprintf(fid, line + "
\n"); end -end -end + fprintf(fid, " "); + + fclose(fid); + + end