Add docs

documentation/all_docs_ref/all_refs.md

@@ -41,22 +41,18 @@
 Note: module names ending with a **\*** mean that they have not yet been ported to GMT.jl and
 its use requires resorting to the \myreflink{Monolithic} mode.
 
-## Utility functions*
+## Utility functions
 
 | | | | | | | | | | |
 |:-----|:----|:----|:----|:----|:----|:----|:----|:----|:----|
-| \myreflink{ablines} | \myreflink{append2fig} | \myreflink{blendimg!} | \myreflink{colorzones!} | \myreflink{cpt4dcw} | \myreflink{crop} | \myreflink{cubeplot} | \myreflink{imagesc} | \myreflink{inwhichpolygon} | \myreflink{lelandshade} |
-| \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{gadm} | \myreflink{geocoder} | \myreflink{geodetic2enu} | \myreflink{info} | \myreflink{lelandshade} | \myreflink{linearfitxy} | \myreflink{getbyattrib} | \myreflink{gmtread} |
-| \myreflink{gmtwrite} | \myreflink{graticules} | \myreflink{gridit} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} |
-| \myreflink{mosaic} | \myreflink{orbits} | \myreflink{pca} | \myreflink{plotgrid!} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{rescale} | \myreflink{slicecube} | \myreflink{stackgrids} | \myreflink{theme} |
-| \myreflink{wmsinfo} | \myreflink{wmsread} | \myreflink{wmstest} | \myreflink{worldrectgrid} | \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} | | | |
-
-## Utility functions
-
-{{ generate_tablerefs utilfuns}}
+| \myreflink{ablines} | \myreflink{append2fig} | \myreflink{blendimg!} | \myreflink{cart2pol} | \myreflink{cart2sph} | \myreflink{colorzones!} | \myreflink{cpt4dcw} | \myreflink{crop} | \myreflink{cubeplot} | \myreflink{date2doy} |
+| \myreflink{delrows!} | \myreflink{doy2date} | \myreflink{imagesc} | \myreflink{inwhichpolygon} | \myreflink{lelandshade} | \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{gadm} | \myreflink{geocoder} | \myreflink{geodetic2enu} |
+| \myreflink{getbyattrib} | \myreflink{gmtread} | \myreflink{gmtwrite} | \myreflink{graticules} | \myreflink{gridit} | \myreflink{gunique} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} |
+| \myreflink{info} | \myreflink{isnodata} | \myreflink{lelandshade} | \myreflink{linearfitxy} | \myreflink{magic} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} | \myreflink{mosaic} | \myreflink{ODE2ds} |
+| \myreflink{orbits} | \myreflink{pca} | \myreflink{plotgrid!} | \myreflink{plotyy} \myreflink{pol2cart} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{regiongeog} | \myreflink{rescale} | \myreflink{slicecube} | \myreflink{sph2cart} |
+| \myreflink{stackgrids} | \myreflink{ter2cart} | \myreflink{theme} | \myreflink{uniqueind} | \myreflink{vecangles} | \myreflink{wmsinfo} | \myreflink{wmsread} | \myreflink{wmstest} | \myreflink{worldrectgrid} | \myreflink{worldrectcoast} |
+| \myreflink{worldrectangular} | \myreflink{xyzw2cube} | \myreflink{yeardecimal} | | | | | | | |
 
-Note: This table contains links to the manuals that were automatically generated from the docstrings.
-Idealy, they should all be converted to individual man pages and moved to table above.
 
 ## GDAL utility functions
 

documentation/common_opts/common_opts.md

@@ -35,7 +35,7 @@ or a pattern.
 
 Use *noframe=true* to have no frame and annotations at all [Default is controlled by the codes].
 
-Optionally append *pole="plon/plat"* (or *pole=(plon,plat)* to draw oblique gridlines about
+Optionally append *pole="plon/plat"* (or *pole=(plon,plat)*) to draw oblique gridlines about
 specified pole [regular gridlines]. Ignored if gridlines are not requested (below) and disallowed for the oblique
 Mercator projection.
 

documentation/modules/blockmean.md

@@ -122,6 +122,5 @@ The same as above but this time returns the two grids to the Julia REPL
 See Also
 --------
 
-The [`GMT man page`](http:https://docs.generic-mapping-tools.org/latest/blockmean.html)
 \myreflink{blockmedian}
 \myreflink{blockmode}

documentation/modules/blockmedian.md

@@ -132,6 +132,5 @@ The same as above but this time returns the two grids to the Julia REPL
 See Also
 --------
 
-The [`GMT man page`](http:https://docs.generic-mapping-tools.org/latest/blockmean.html)
 \myreflink{blockmean}
 \myreflink{blockmode}

documentation/modules/blockmode.md

@@ -133,6 +133,5 @@ field_z.nc and field_s.nc, run:
 See Also
 --------
 
-The [`GMT man page`](http:https://docs.generic-mapping-tools.org/latest/blockmean.html)
 \myreflink{blockmean}
 \myreflink{blockmedian}

documentation/modules/boxplot.md

@@ -9,7 +9,7 @@ boxplot(data, grp=[]; pos=nothing, kwargs...)
 Draw a box-and-whisker style plot. The input data can take several different forms.
 
 ---
-boxplot(data::AbstractVector{<:Real}; kwargs...)
+``boxplot(data::AbstractVector{<:Real}; kwargs...)``
 
 Draws a single boxplot. Options in *kwargs* provide fine settings for the boxplot
 
@@ -31,24 +31,24 @@ Draws a single boxplot. Options in *kwargs* provide fine settings for the boxplo
  where first element is an AbstractArray and second an array or tuple of strings or symbols.
 
 ---
-boxplot(data::AbstractVector{<:Real}, grp::AbstractVector, ...) Use the categorical vector (made of integers
+``boxplot(data::AbstractVector{<:Real}, grp::AbstractVector, ...)`` Use the categorical vector (made of integers
 or text strings) `grp` break down a the `data` column vector in cathegories (groups).
 
 ---
-boxplot(data::AbstractMatrix{<:Real}; pos=Vector{<:Real}, ...) where `pos` is a coordinate vector (or a single
+``boxplot(data::AbstractMatrix{<:Real}; pos=Vector{<:Real}, ...)`` where `pos` is a coordinate vector (or a single
 location when `data` is a vector) where to plot the boxes. Default plots them at 1:n_boxes or 1:n_groups.
 
 ---
-boxplot(data::GMTdatset{<:Real}; pos=Vector{Real}(), ...) Like the above case but the input data is stored
+``boxplot(data::GMTdatset{<:Real}; pos=Vector{Real}(), ...)`` Like the above case but the input data is stored
 in a \myreflink{GMTdataset}
 
 ---
-boxplot(data::Vector{Vector{<:Real}}; pos=Vector{Real}(), ...) Similar to the Matrix case but here each data
+``boxplot(data::Vector{Vector{<:Real}}; pos=Vector{Real}(), ...)`` Similar to the Matrix case but here each data
 vector used to compute the statistics can have a different number of points. There will be as many boxplots as
 `length(data)`
 
 ---
-boxplot(data::Array{T<:Real,3}; pos=Vector{Real}(), groupwidth=0.75, ccolor=false, ...) Draws *G* groups of
+``boxplot(data::Array{T<:Real,3}; pos=Vector{Real}(), groupwidth=0.75, ccolor=false, ...)`` Draws *G* groups of
 boxplots of *N* columns boxes.
 - `groupWidth`: Specify the proportion of the x-axis interval across which each x-group of boxes should
  be spread. The default is 0.75.
@@ -64,7 +64,7 @@ boxplots of *N* columns boxes.
  where first element is an AbstractArray and second an array or tuple of strings or symbols.
 
 ---
-boxplot(data::Vector{Vector{Vector{<:Real}}}, ...) Like the above but here the groups (`length(data)`)
+``boxplot(data::Vector{Vector{Vector{<:Real}}}, ...)`` Like the above but here the groups (`length(data)`)
 can have a variable number of elements and each have its own size.
 
 -----------

documentation/modules/clip.md

@@ -93,7 +93,7 @@ being partly visible or missing altogether, try:
 ```julia
 using GMT
 clip([0 0; 5 1; 5 5], region=(0,6,0,6), figscale=2.5, pen=(1,:blue))
-plot("@tut_data.txt", fill=:red, marker=:circ, ms=2)
+plot!("@tut_data.txt", fill=:red, marker=:circ, ms=2, region=:same)
 clip!(endclip=true, frame=:same, show=true)
 ```
 \end{examplefig}

documentation/modules/colorbar.md

@@ -35,7 +35,7 @@ Optional Arguments
  Where *cpt* is the CPT to be used. By default all color changes are annotated. To use a subset, add an extra column to the CPT with a L, U, or B to annotate Lower, Upper, or Both color segment boundaries (but see **frame**). We can understand pattern specifications in the CPT. For CPTs where the *z* range is in meters, it may be useful to change to another unit when plotting. To do so, append **+U**unit to the file name. Likewise, if the CPT uses another unit than meter and you wish to plot the CPT versus meters, append **+u**unit. If a GMT master dynamic CPT is given instead then its *z*-range will be set to its default range (if it has one) before plotting.
 
 - **F** or **box** : -- *box=(clearance=val, fill=color, inner=true, pen=pen, rounded=true, shaded=XX)*\
- Without further options, draws a rectangular border around the scale using `MAP_FRAME_PEN`; specify a different pen with **pen=pen**, (see \myreflink{Pen attributes}. Add **fill=color**, where *color* is any valid color setting (see \myreflink{Setting color}, to fill the scale panel [no fill]. Add **clearance=val** where *val* is either *gap* or *(xgap,ygap)*, or *(lgap,rgap,bgap,tgap)* where these items are uniform, separate in x- and y-direction, or individual side spacings between scale and border. Use **inner=true** to draw a secondary, inner border as well. We use a uniform *gap* between borders of *2p* and the `MAP_DEFAULTS_PEN` unless other values are specified (like **inner="gap/pen"**). Add **rounded=true** to draw rounded rectangular borders instead, with a *6p* corner radius. You can override this radius by using another value instead of *true*. Finally, use **shadded=true** or **shadded=(dx,dy)** or **shadded=shade** to draw an offset background shaded region. Here, *dx/dy* indicates the shift relative to the foreground frame [*4p/-4p*]and *shade* sets the fill style to use for shading ("gray50").
+ Without further options, draws a rectangular border around the scale using `MAP_FRAME_PEN`; specify a different pen with **pen=pen**, (see \myreflink{Pen attributes}). Add **fill=color**, where *color* is any valid color setting (see \myreflink{Setting color}), to fill the scale panel [no fill]. Add **clearance=val** where *val* is either *gap* or *(xgap,ygap)*, or *(lgap,rgap,bgap,tgap)* where these items are uniform, separate in x- and y-direction, or individual side spacings between scale and border. Use **inner=true** to draw a secondary, inner border as well. We use a uniform *gap* between borders of *2p* and the `MAP_DEFAULTS_PEN` unless other values are specified (like **inner="gap/pen"**). Add **rounded=true** to draw rounded rectangular borders instead, with a *6p* corner radius. You can override this radius by using another value instead of *true*. Finally, use **shadded=true** or **shadded=(dx,dy)** or **shadded=shade** to draw an offset background shaded region. Here, *dx/dy* indicates the shift relative to the foreground frame [*4p/-4p*]and *shade* sets the fill style to use for shading ("gray50").
 
 - **G** or **truncate** : -- *truncate=(zlo,zhi)*\
  Truncate the incoming CPT so that the lowest and highest z-levels are to *zlo* and *zhi*. If one of these equal NaN then we leave that end of the CPT alone. The truncation takes place before the plotting.

documentation/modules/feather.md

@@ -98,7 +98,7 @@ Show the data used in this example.
 using GMT, PrettyTables # hide
 getpath4docs(file::String) = joinpath("..", "..", "..", "..", "..", file) # hide
 io = IOBuffer() # hide
-D = gmtread(getpath4docs("wind_faro_s.dat"))
+D = gmtread(GMT.TESTSDIR * "wind_faro_s.dat")
 pretty_table(io, D.data; header=D.colnames, backend=Val(:html)) # hide
 println("~~~" * String(take!(io)) * "~~~") # hide
 ```
@@ -112,6 +112,6 @@ in the plot. We select the columns from teir names in the `D` *GMTdataset*.
 ```julia
 using GMT
 GMT.resetGMT() # hide
-feather(getpath4docs("wind_faro.dat"), xvar=:Time, yvar=[:azimuth, :vmean], rtheta=true, nohead=1, lw=0.1, show=true)
+feather(GMT.TESTSDIR * "wind_faro.dat", xvar=:Time, yvar=[:azimuth, :vmean], rtheta=true, nohead=1, lw=0.1, show=true)
 ```
 \end{examplefig}

documentation/modules/gmtsplit.md

@@ -90,8 +90,6 @@ Optional Arguments
 .. |Add_-g| replace:: Do not let a segment have a gap exceeding *gap*; instead, split it into two segments. [Default ignores gaps].
 \textinput{common_opts/opt_h}
 
-\textinput{common_opts/opt_h}
-
 \textinput{common_opts/opt__i}
 
 \textinput{common_opts/opt_q}

documentation/modules/parallelplot.md

@@ -97,7 +97,7 @@ identified in species, and label the horizontal axis using the variable names.
 \begin{examplefig}{}
 ```julia
 using GMT
-parallelplot(getpath4docs("iris.dat"), groupvar="text", normalize="none", legend=true, show=true)
+parallelplot(GMT.TESTSDIR * "iris.dat", groupvar="text", normalize="none", legend=true, show=true)
 ```
 \end{examplefig}
 
@@ -107,7 +107,7 @@ Label the horizontal axis using the variable names.
 \begin{examplefig}{}
 ```julia
 using GMT
-parallelplot(getpath4docs("iris.dat"), groupvar="text", quantile=0.25, legend=true, show=true)
+parallelplot(GMT.TESTSDIR * "iris.dat", groupvar="text", quantile=0.25, legend=true, show=true)
 ```
 \end{examplefig}
 
@@ -116,6 +116,6 @@ Plot bands enveloping the +- 25% percentil arround the median.
 \begin{examplefig}{}
 ```julia
 using GMT
-parallelplot(getpath4docs("iris.dat"), groupvar="text", band=true, legend=true, show=true)
+parallelplot(GMT.TESTSDIR * "iris.dat", groupvar="text", band=true, legend=true, show=true)
 ```
 \end{examplefig}

documentation/modules/project.md

@@ -113,7 +113,7 @@ Required Arguments
 - *table*\
  One or more data tables holding a number of data columns.
 
-- **C** or **origin** or **center** : -- *origin=(cx, cy)*\
+- **C** or **origin** or **start_point** : -- *origin=(cx, cy)*\
  Set the origin *cx,cy* of the projection when used with **azim** or **endpoint** or set the coordinates *cx,cy* of a point
  through which the oblique zero meridian ($p = 0$) should pass when used with **pole**. *cx,cy* is not required
  to be 90 degrees from the pole set by **pole**.
@@ -253,7 +253,7 @@ To generate points every 10 km along a small circle of colatitude 60 from 10N,50
 \begin{examplefig}{}
 ```julia
 using GMT
-Dsc = project(center=(-50,10), endpoint=(-10,30), step=(10,60), km=true)
+Dsc = project(origin=(-50,10), endpoint=(-10,30), step=(10,60), km=true)
 imshow(Dsc, marker=:point, lw=0.5, coast=true)
 ```
 \end{examplefig}

documentation/modules/surface.md

@@ -38,8 +38,6 @@ Required Arguments
 
 \textinput{common_opts/opt_I}
 
-\textinput{common_opts/opt_J}
-
 Optional Arguments
 ------------------
 

documentation/modules/vband.md

@@ -91,7 +91,7 @@ We can fill with patterns as well. And use an image as one of the patterns.
 \begin{examplefig}{}
 ```julia
 using GMT
-vband([1 2; 2.5 4], fill=((pattern=getpath4docs("tiling2.jpg"), dpi=200), (pattern=27, dpi=200)),
+vband([1 2; 2.5 4], fill=((pattern=GMT.TESTSDIR * "tiling2.jpg", dpi=200), (pattern=27, dpi=200)),
  region=(0,5,-1,5), show=true)
 ```
 \end{examplefig}

documentation/modules/wiggle.md

@@ -83,8 +83,6 @@ Optional Arguments
 
 \textinput{common_opts/opt_V}
 
-\textinput{common_opts/opt_pen}
-
 \textinput{common_opts/opt_X}
 
 \textinput{common_opts/opt_Y}

documentation/utilities/ODE2ds.md

@@ -0,0 +1,10 @@
+# ODE2ds
+
+```
+D = ODE2ds(sol; interp=0)
+```
+
+Extract data from a DifferentialEquations solution type and return it into a GMTdataset.
+
+- `interp`: == 0 means we return the original points (no interpolation). == 2 => do data interpolation to
+ the double of original number of points. == 3 => three times, == n => n times.

documentation/utilities/cart2pol.md

@@ -0,0 +1,7 @@
+# cart2pol
+
+```
+theta, rho = cart2pol(x, y; deg=false)
+```
+
+Transform Cartesian to polar coordinates. Angles are returned in radians by default. Use `deg=true` to return the angles in degrees. Input can be scalar, vectors or matrices.

documentation/utilities/cart2sph.md

@@ -0,0 +1,8 @@
+# cart2sph
+
+```
+az, elev, rho = cart2sph(x, y, z; deg=false)
+```
+
+Transform Cartesian coordinates to spherical. Angles are returned in radians by default. Use `deg=true`
+to return the angles in degrees. Input can be scalar, vectors or matrices.

documentation/utilities/colorzones.md

@@ -55,8 +55,6 @@ Read the 2020 Sentinel2 Earth color for Portugal at 100 m resolution. Load the a
 regions and compute their median colors.
 
 ```julia
-using GMT
-
 wms = wmsinfo("http:https://tiles.maps.eox.at/wms?");
 img = wmsread(wms, layer=3, region=(-9.6,-6,36.9,42.2), pixelsize=100);
 Pt = gmtread("C:/programs/compa_libs/covid19pt/extra/mapas/concelhos/concelhos.shp");

documentation/utilities/date2doy.md

@@ -0,0 +1,7 @@
+# date2doy
+
+```
+date2doy(date) -> Integer
+```
+
+Compute the Day-Of-Year (DOY) from `date` that can be a string or a Date/DateTime type. If ommited, returns today's DOY

documentation/utilities/delrows.md

@@ -0,0 +1,7 @@
+# delrows!
+
+```
+delrows!(A::Matrix, rows::VecOrMat)
+```
+
+Delete the rows of Matrix `A` listed in the vector `rows`

documentation/utilities/df2ds.md

@@ -0,0 +1,7 @@
+# df2ds
+
+```
+D = df2ds(df)
+```
+
+Extract numeric data from a DataFrame type and return it into a GMTdataset. Works only with 'simple' DataFrames.

documentation/utilities/doy2date.md

@@ -0,0 +1,7 @@
+# doy2date
+
+```
+doy2date(doy[, year]) -> Date
+```
+
+Compute the date from the Day-Of-Year `doy`. If `year` is ommited we take it to mean the current year. Both `doy` and `year` can be strings or integers.

documentation/utilities/gunique.md

@@ -0,0 +1,7 @@
+# gunique
+
+```
+u, ind = gunique(x::AbstractVector; sorted=false)
+```
+
+Return an array containing only the unique elements of `x` and the indices `ind` such that `u = x[ind]`. If `sorted` is true the output is sorted (default is not)

documentation/utilities/image_alpha.md

@@ -18,16 +18,12 @@ Examples
 Change to the third color in cmap to represent the new transparent color
 
 ```julia
-using GMT
-
 image_alpha!(img, alpha_ind=3)
 ```
 
 Change to the first 6 colors in cmap by assigning them random values
 
 ```julia
-using GMT
-
 image_alpha!(img, alpha_vec=round.(Int32,rand(6).*255))
 ```
 

documentation/utilities/imagesc.md

@@ -1,7 +1,7 @@
 # imagesc
 
 ```julia
-I = imagesc(mat; x=, y=, hdr=, proj4=, wkt=, GI=, clim=, cmap=, kw...) --> \myreflink{grdimage}
+I = imagesc(mat; x=, y=, hdr=, proj4=, wkt=, GI=, clim=, cmap=, kw...) --> GMTimage
 ```
 
 *keywords: GMT, Julia, grid, image*

documentation/utilities/isnodata.md

@@ -0,0 +1,7 @@
+# isnodata
+
+```
+isnodata(array::AbstractArray, val=0)
+```
+
+Return a boolean array with the same size a `array` with 1's (`true`) where ``array[i] == val``.

documentation/utilities/magic.md

@@ -0,0 +1,7 @@
+# magic
+
+ M = magic(n::Int) => Matrix{Int}
+
+M = magic(n) returns an n-by-n matrix constructed from the integers 1 through n^2 with equal row
+and column sums. The order n must be a scalar greater than or equal to 3 in order to create a
+valid magic square.

documentation/utilities/plotyy.md

@@ -0,0 +1,11 @@
+# plotyy
+
+```
+plotyy(arg1, arg2; kwargs...)
+```
+
+Example:
+
+```julia
+plotyy([1 1; 2 2], [1.5 1.5; 3 3], R="0.8/3/0/5", title="Ai", ylabel=:Bla, xlabel=:Ble, seclabel=:Bli, show=1)
+```

documentation/utilities/regiongeog.md

@@ -0,0 +1,9 @@
+# regiongeog
+
+```
+regiongeog(GI) --> Tuple{Float64}
+```
+
+Returns a tuple with (lon*min, lon*max, lat*min, lat*max) of the projected `GI` object limits converted
+to geographic coordinates. Returns an empty tuple if `GI` has no registered referencing system.
+`GI` can either a `GMTgrid`, a `GMTimage` or a file name (String) of one those types.

documentation/utilities/sph2cart.md

@@ -0,0 +1,8 @@
+# sph2cart
+
+```
+x, y, z = sph2cart(az, elev, rho; deg=false)
+```
+
+Transform spherical coordinates to Cartesian. Angles are in radians by default. Use `deg=true` if angles
+are in degrees. Input can be scalar, vectors or matrices.

documentation/utilities/uniqueind.md

@@ -0,0 +1,7 @@
+# uniqueind
+
+```
+ind = uniqueind(x)
+```
+
+Return the index `ind` such that x[ind] gets the unique values of x. No sorting is done