more doc system fixes

Author: thchr

Bravais/src/Bravais.jl

@@ -27,6 +27,7 @@ export crystal,
     reciprocalbasis,
     AbstractBasis,
     volume,
+    metricmatrix,
     DirectBasis,
     ReciprocalBasis,
     AbstractPoint,

Bravais/src/types.jl

@@ -53,32 +53,39 @@ function angles(Rs::AbstractBasis{3})
 end
 angles(::AbstractBasis{D}) where D = _throw_invalid_dim(D)
 
+if VERSION < v"1.9.0-DEV.1163" 
+    # since https://github.com/JuliaLang/julia/pull/43334, Julia defines its own `stack`;
+    # however, it is still much slower than a naive implementation based on `reduce` cf.
+    # https://github.com/JuliaLang/julia/issues/52590. As such, we extend `Base.stack` even
+    # on more recent versions; when the issue is fixed, it would be enough to only define
+    # `stack` on earlier versions of Julia, falling back to `Base.stack` on later versions.
+    import Base: stack
+end
 """
     stack(Vs::AbstractBasis)
 
-Return a matrix `[Vs[1] Vs[2] .. Vs[D]]` from `Vs::AbstractBasis{D}`, i.e. the matrix whose
+Return a matrix `[Vs[1] Vs[2] .. Vs[D]]` from `Vs::AbstractBasis{D}`, i.e., the matrix whose
 columns are the basis vectors of `Vs`.
 """
 stack(Vs::AbstractBasis) = reduce(hcat, parent(Vs))
-# TODO: At some point, this should hopefully no longer be necessary to do manually (and
-# `stack` may end up exported by Base): https://github.com/JuliaLang/julia/issues/21672
 
 """
     volume(Vs::AbstractBasis)
 
 Return the volume ``V`` of the unit cell associated with the basis `Vs::AbstractBasis{D}`.
 
-The volume is computed as ``V = \\sqrt{\\mathrm{det}G}`` with with ``G`` denoting the metric
-matrix of `Vs` (cf. the International Tables of Crystallography, Volume A, Section 5.2.2.3).
+The volume is computed as ``V = \\sqrt{\\mathrm{det}\\mathbf{G}}`` with with ``\\mathbf{G}``
+denoting the metric matrix of `Vs` (cf. the International Tables of Crystallography, 
+Volume A, Section 5.2.2.3).
 
-See also [`Bravais.metricmatrix`](@ref).
+See also [`metricmatrix`](@ref).
 """
-volume(Vs::AbstractBasis) = sqrt(det(metricmatrix(Vs))) # TODO: wrong. TODO: export.
+volume(Vs::AbstractBasis) = sqrt(det(metricmatrix(Vs)))
 
 """
     metricmatrix(Vs::AbstractBasis)
 
-Return the (real, symmetric) metric matrix of a basis `Vs`, i.e. the matrix with elements
+Return the (real, symmetric) metric matrix of a basis `Vs`, i.e., the matrix with elements
 ``G_{ij} =`` `dot(Vs[i], Vs[j])`, as defined in the International Tables of Crystallography,
 Volume A, Section 5.2.2.3.
 

Bravais/src/utils.jl

@@ -2,7 +2,7 @@
 # in here to avoid taking on that dependency (long load time; ~7 s)
 uniform_rand(low::Real, high::Real) = low + (high - low) * rand()
 
-"""
+#=
     relrand(lims::NTuple{2,Real}) --> Float64
 
 Computes a random number in the range specified by the two-element 
@@ -14,7 +14,7 @@ interval [-1/`lims[1]`, -1] ∪ [1, `lims[2]`].
 This is useful for ensuring an even sampling of numbers that are
 either smaller or larger than unity. E.g. for `x = relrand((0.2,5.0))`,
 `x` is equally probable to fall in inv(`x`)∈[1,5] or `x`∈[1,5].
-"""
+=#
 function relrand(lims::NTuple{2,<:Real})
     low, high = lims; invlow = inv(low)
     lowthres = (invlow - 1.0)/(invlow + high - 2.0)

docs/src/api.md

@@ -20,6 +20,13 @@ Private = false
 Order   = [:function]
 ```
 
+## Exported macros
+```@autodocs
+Modules = [Crystalline]
+Private = false
+Order   = [:macro]
+```
+
 ## Exported constants
 ```@autodocs
 Modules = [Crystalline]

docs/src/bravais.md

@@ -10,8 +10,10 @@ CurrentModule = Bravais
 
 ### Types
 ```@docs
+AbstractBasis
 DirectBasis
 ReciprocalBasis
+AbstractPoint
 DirectPoint
 ReciprocalPoint
 ```
@@ -47,6 +49,17 @@ conventionalize(::DirectBasis, ::Union{Char, <:Integer})
 conventionalize(::ReciprocalBasis, ::Union{Char, <:Integer})
 conventionalize(::DirectPoint, ::Union{Char, <:Integer})
 conventionalize(::ReciprocalPoint, ::Union{Char, <:Integer})
+cartesianize
+cartesianize!
+latticize
+latticize!
+```
+
+### Miscellaneous
+```@docs
+volume
+metricmatrix
+stack
 ```
 
 ## Crystalline.jl extensions of Bravais.jl functions

src/symops.jl

@@ -606,7 +606,16 @@ function littlegroup(ops::AbstractVector{SymOperation{D}}, kv::KVec{D},
     end
     return idxlist, view(ops, idxlist)
 end
-function littlegroup(sg::SpaceGroup, kv::KVec) 
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the little group associated with space group `sg` at the **k**-vector `kv`.
+
+Optionally, an associated **k**-vector label `klab` can be provided; if not provided, the
+empty string is used as label.
+"""
+function littlegroup(sg::SpaceGroup, kv::KVec, klab::String="") 
     _, lgops = littlegroup(operations(sg), kv, centering(sg))
     return LittleGroup{dim(sg)}(num(sg), kv, "", lgops)
 end