Merge pull request #17272 from MichaelHatherly/mh/admonition-syntax

Add admonition syntax to markdown parser

base/docs/helpdb/Base.jl

@@ -361,18 +361,6 @@ Returns `true` if `path` is a regular file, `false` otherwise.
 """
 isfile
 
-"""
-    symlink(target, link)
-
-Creates a symbolic link to `target` with the name `link`.
-
-**note**
-
-This function raises an error under operating systems that do not support soft symbolic
-links, such as Windows XP.
-"""
-symlink
-
 """
     task_local_storage(symbol)
 
@@ -2320,64 +2308,6 @@ For matrices or vectors ``A`` and ``B``, calculates ``A / Bᴴ``.
 """
 A_rdiv_Bc
 
-"""
-    round([T,] x, [digits, [base]], [r::RoundingMode])
-
-`round(x)` rounds `x` to an integer value according to the default rounding mode (see
-[`rounding`](:func:`rounding`)), returning a value of the same type as `x`. By default
-([`RoundNearest`](:obj:`RoundNearest`)), this will round to the nearest integer, with ties
-(fractional values of 0.5) being rounded to the even integer.
-
-```jldoctest
-julia> round(1.7)
-2.0
-
-julia> round(1.5)
-2.0
-
-julia> round(2.5)
-2.0
-```
-
-The optional [`RoundingMode`](:obj:`RoundingMode`) argument will change how the number gets
-rounded.
-
-`round(T, x, [r::RoundingMode])` converts the result to type `T`, throwing an
-[`InexactError`](:exc:`InexactError`) if the value is not representable.
-
-`round(x, digits)` rounds to the specified number of digits after the decimal place (or
-before if negative). `round(x, digits, base)` rounds using a base other than 10.
-
-```jldoctest
-julia> round(pi, 2)
-3.14
-
-julia> round(pi, 3, 2)
-3.125
-```
-
-**note**
-
-Rounding to specified digits in bases other than 2 can be inexact when operating on binary
-floating point numbers. For example, the `Float64` value represented by `1.15` is actually
-*less* than 1.15, yet will be rounded to 1.2.
-
-```jldoctest
-julia> x = 1.15
-1.15
-
-julia> @sprintf "%.20f" x
-"1.14999999999999991118"
-
-julia> x < 115//100
-true
-
-julia> round(x, 1)
-1.2
-```
-"""
-round(T::Type, x)
-
 """
     round(z, RoundingModeReal, RoundingModeImaginary)
 
@@ -4416,33 +4346,6 @@ Bessel function of the third kind of order `nu`, ``H^{(1)}_\\nu(x)``.
 """
 hankelh1
 
-"""
-    gcdx(x,y)
-
-Computes the greatest common (positive) divisor of `x` and `y` and their Bézout
-coefficients, i.e. the integer coefficients `u` and `v` that satisfy
-``ux+vy = d = gcd(x,y)``.
-
-```jldoctest
-julia> gcdx(12, 42)
-(6,-3,1)
-```
-
-```jldoctest
-julia> gcdx(240, 46)
-(2,-9,47)
-```
-
-**note**
-
-Bézout coefficients are *not* uniquely defined. `gcdx` returns the minimal Bézout
-coefficients that are computed by the extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e,
-p. 325, Algorithm X.) These coefficients `u` and `v` are minimal in the sense that
-``|u| < |\\frac y d`` and ``|v| < |\\frac x d``. Furthermore, the signs of `u` and `v` are
-chosen so that `d` is positive.
-"""
-gcdx
-
 """
     rem(x, y)
     %(x, y)
@@ -8627,72 +8530,6 @@ Converts the endianness of a value from Network byte order (big-endian) to that
 """
 ntoh
 
-"""
-    qrfact(A [,pivot=Val{false}]) -> F
-
-Computes the QR factorization of `A`. The return type of `F` depends on the element type of
-`A` and whether pivoting is specified (with `pivot==Val{true}`).
-
-| Return type   | `eltype(A)`     | `pivot`      | Relationship between `F` and `A` |
-|:--------------|:----------------|:-------------|:---------------------------------|
-| `QR`          | not `BlasFloat` | either       | `A==F[:Q]*F[:R]`                 |
-| `QRCompactWY` | `BlasFloat`     | `Val{false}` | `A==F[:Q]*F[:R]`                 |
-| `QRPivoted`   | `BlasFloat`     | `Val{true}`  | `A[:,F[:p]]==F[:Q]*F[:R]`        |
-
-`BlasFloat` refers to any of: `Float32`, `Float64`, `Complex64` or `Complex128`.
-
-The individual components of the factorization `F` can be accessed by indexing:
-
-| Component | Description                               | `QR`            | `QRCompactWY`      | `QRPivoted`     |
-|:----------|:------------------------------------------|:----------------|:-------------------|:----------------|
-| `F[:Q]`   | `Q` (orthogonal/unitary) part of `QR`     | ✓ (`QRPackedQ`) | ✓ (`QRCompactWYQ`) | ✓ (`QRPackedQ`) |
-| `F[:R]`   | `R` (upper right triangular) part of `QR` | ✓               | ✓                  | ✓               |
-| `F[:p]`   | pivot `Vector`                            |                 |                    | ✓               |
-| `F[:P]`   | (pivot) permutation `Matrix`              |                 |                    | ✓               |
-
-The following functions are available for the `QR` objects: `size`, `\\`. When `A` is
-rectangular, `\\` will return a least squares solution and if the solution is not unique,
-the one with smallest norm is returned.
-
-Multiplication with respect to either thin or full `Q` is allowed, i.e. both `F[:Q]*F[:R]`
-and `F[:Q]*A` are supported. A `Q` matrix can be converted into a regular matrix with
-[`full`](:func:`full`) which has a named argument `thin`.
-
-**note**
-
-`qrfact` returns multiple types because LAPACK uses several representations that minimize
-the memory storage requirements of products of Householder elementary reflectors, so that
-the `Q` and `R` matrices can be stored compactly rather as two separate dense matrices.
-
-The data contained in `QR` or `QRPivoted` can be used to construct the `QRPackedQ` type,
-which is a compact representation of the rotation matrix:
-
-```math
-Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T)
-```
-
-where ``\\tau_i`` is the scale factor and ``v_i`` is the projection vector associated with
-the ``i^{th}`` Householder elementary reflector.
-
-The data contained in `QRCompactWY` can be used to construct the `QRCompactWYQ` type,
-which is a compact representation of the rotation matrix
-
-```math
-Q = I + Y T Y^T
-```
-
-where `Y` is ``m \\times r`` lower trapezoidal and `T` is ``r \\times r`` upper
-triangular. The *compact WY* representation [^Schreiber1989] is not to be confused with the
-older, *WY* representation [^Bischof1987]. (The LAPACK documentation uses `V` in lieu of `Y`.)
-
-[^Bischof1987]: C Bischof and C Van Loan, "The WY representation for products of Householder matrices", SIAM J Sci Stat Comput 8 (1987), s2-s13. [doi:10.1137/0908009](http://dx.doi.org/10.1137/0908009)
-
-[^Schreiber1989]: R Schreiber and C Van Loan, "A storage-efficient WY representation for products of Householder transformations", SIAM J Sci Stat Comput 10 (1989), 53-57. [doi:10.1137/0910005](http://dx.doi.org/10.1137/0910005)
-
-"""
-qrfact(A,?)
-
-
 """
     qrfact(A) -> SPQR.Factorization
 

base/docs/utils.jl

@@ -368,6 +368,7 @@ stripmd(x::AbstractString) = x  # base case
 stripmd(x::Void) = " "
 stripmd(x::Vector) = string(map(stripmd, x)...)
 stripmd(x::Markdown.BlockQuote) = "$(stripmd(x.content))"
+stripmd(x::Markdown.Admonition) = "$(stripmd(x.content))"
 stripmd(x::Markdown.Bold) = "$(stripmd(x.text))"
 stripmd(x::Markdown.Code) = "$(stripmd(x.code))"
 stripmd{N}(x::Markdown.Header{N}) = stripmd(x.text)

base/file.jl

@@ -422,6 +422,16 @@ end
 if is_windows()
     const UV_FS_SYMLINK_JUNCTION = 0x0002
 end
+
+"""
+    symlink(target, link)
+
+Creates a symbolic link to `target` with the name `link`.
+
+!!! note
+    This function raises an error under operating systems that do not support
+    soft symbolic links, such as Windows XP.
+"""
 function symlink(p::AbstractString, np::AbstractString)
     @static if is_windows()
         if Sys.windows_version() < Sys.WINDOWS_VISTA_VER

base/floatfuncs.jl

@@ -48,6 +48,63 @@ end
 @vectorize_1arg Number isinf
 @vectorize_1arg Number isfinite
 
+"""
+    round([T,] x, [digits, [base]], [r::RoundingMode])
+
+`round(x)` rounds `x` to an integer value according to the default rounding mode (see
+[`rounding`](:func:`rounding`)), returning a value of the same type as `x`. By default
+([`RoundNearest`](:obj:`RoundNearest`)), this will round to the nearest integer, with ties
+(fractional values of 0.5) being rounded to the even integer.
+
+```jldoctest
+julia> round(1.7)
+2.0
+
+julia> round(1.5)
+2.0
+
+julia> round(2.5)
+2.0
+```
+
+The optional [`RoundingMode`](:obj:`RoundingMode`) argument will change how the number gets
+rounded.
+
+`round(T, x, [r::RoundingMode])` converts the result to type `T`, throwing an
+[`InexactError`](:exc:`InexactError`) if the value is not representable.
+
+`round(x, digits)` rounds to the specified number of digits after the decimal place (or
+before if negative). `round(x, digits, base)` rounds using a base other than 10.
+
+```jldoctest
+julia> round(pi, 2)
+3.14
+
+julia> round(pi, 3, 2)
+3.125
+```
+
+!!! note
+    Rounding to specified digits in bases other than 2 can be inexact when
+    operating on binary floating point numbers. For example, the `Float64`
+    value represented by `1.15` is actually *less* than 1.15, yet will be
+    rounded to 1.2.
+
+    ```jldoctest
+    julia> x = 1.15
+    1.15
+
+    julia> @sprintf "%.20f" x
+    "1.14999999999999991118"
+
+    julia> x < 115//100
+    true
+
+    julia> round(x, 1)
+    1.2
+    ```
+"""
+round(T::Type, x)
 
 round(x::Real, ::RoundingMode{:ToZero}) = trunc(x)
 round(x::Real, ::RoundingMode{:Up}) = ceil(x)

base/intfuncs.jl

@@ -48,6 +48,31 @@ gcd{T<:Integer}(abc::AbstractArray{T}) = reduce(gcd,abc)
 lcm{T<:Integer}(abc::AbstractArray{T}) = reduce(lcm,abc)
 
 # return (gcd(a,b),x,y) such that ax+by == gcd(a,b)
+"""
+    gcdx(x,y)
+
+Computes the greatest common (positive) divisor of `x` and `y` and their Bézout
+coefficients, i.e. the integer coefficients `u` and `v` that satisfy
+``ux+vy = d = gcd(x,y)``.
+
+```jldoctest
+julia> gcdx(12, 42)
+(6,-3,1)
+```
+
+```jldoctest
+julia> gcdx(240, 46)
+(2,-9,47)
+```
+
+!!! note
+    Bézout coefficients are *not* uniquely defined. `gcdx` returns the minimal
+    Bézout coefficients that are computed by the extended Euclid algorithm.
+    (Ref: D. Knuth, TAoCP, 2/e, p. 325, Algorithm X.) These coefficients `u`
+    and `v` are minimal in the sense that ``|u| < |\\frac y d`` and ``|v| <
+    |\\frac x d``. Furthermore, the signs of `u` and `v` are chosen so that `d`
+    is positive.
+"""
 function gcdx{T<:Integer}(a::T, b::T)
     s0, s1 = one(T), zero(T)
     t0, t1 = s1, s0

base/linalg/arnoldi.jl

@@ -50,30 +50,29 @@ The following keyword arguments are supported:
 iterations `niter` and the number of matrix vector multiplications `nmult`, as well as the
 final residual vector `resid`.
 
-**note**
-
-The `sigma` and `which` keywords interact: the description of eigenvalues searched for by
-`which` do _not_ necessarily refer to the eigenvalues of `A`, but rather the linear operator
-constructed by the specification of the iteration mode implied by `sigma`.
-
-| `sigma`         | iteration mode                   | `which` refers to eigenvalues of |
-|:----------------|:---------------------------------|:---------------------------------|
-| `nothing`       | ordinary (forward)               | ``A``                            |
-| real or complex | inverse with level shift `sigma` | ``(A - \\sigma I )^{-1}``        |
-
-**note**
-
-Although `tol` has a default value, the best choice depends strongly on the
-matrix `A`. We recommend that users _always_ specify a value for `tol` which
-suits their specific needs.
-
-For details of how the errors in the computed eigenvalues are estimated, see:
-
-* B. N. Parlett, "The Symmetric Eigenvalue Problem", SIAM: Philadelphia, 2/e
-  (1998), Ch. 13.2, "Accessing Accuracy in Lanczos Problems", pp. 290-292 ff.
-* R. B. Lehoucq and D. C. Sorensen, "Deflation Techniques for an Implicitly
-  Restarted Arnoldi Iteration", SIAM Journal on Matrix Analysis and
-  Applications (1996), 17(4), 789–821.  doi:10.1137/S0895479895281484
+!!! note
+    The `sigma` and `which` keywords interact: the description of eigenvalues
+    searched for by `which` do _not_ necessarily refer to the eigenvalues of
+    `A`, but rather the linear operator constructed by the specification of the
+    iteration mode implied by `sigma`.
+
+    | `sigma`         | iteration mode                   | `which` refers to eigenvalues of |
+    |:----------------|:---------------------------------|:---------------------------------|
+    | `nothing`       | ordinary (forward)               | ``A``                            |
+    | real or complex | inverse with level shift `sigma` | ``(A - \\sigma I )^{-1}``        |
+
+!!! note
+    Although `tol` has a default value, the best choice depends strongly on the
+    matrix `A`. We recommend that users _always_ specify a value for `tol`
+    which suits their specific needs.
+
+    For details of how the errors in the computed eigenvalues are estimated, see:
+
+    * B. N. Parlett, "The Symmetric Eigenvalue Problem", SIAM: Philadelphia, 2/e
+      (1998), Ch. 13.2, "Accessing Accuracy in Lanczos Problems", pp. 290-292 ff.
+    * R. B. Lehoucq and D. C. Sorensen, "Deflation Techniques for an Implicitly
+      Restarted Arnoldi Iteration", SIAM Journal on Matrix Analysis and
+      Applications (1996), 17(4), 789–821.  doi:10.1137/S0895479895281484
 """
 eigs(A; kwargs...) = eigs(A, I; kwargs...)
 eigs{T<:BlasFloat}(A::AbstractMatrix{T}, ::UniformScaling; kwargs...) = _eigs(A, I; kwargs...)