Use DocStringExtensions.jl for writing docstrings (#11)

* Use DocStringExtensions to write docstrings

* Add codecov

.github/workflows/CI.yml

@@ -43,3 +43,9 @@ jobs:
       - uses: julia-actions/julia-runtest@v1
         with:
           annotate: true
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v3
+        with:
+          files: lcov.info
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

Project.toml

@@ -1,7 +1,7 @@
 name = "WannierIO"
 uuid = "cb1bc77f-5443-4951-af9f-05b616a3e422"
 authors = ["Junfeng Qiao <qiaojunfeng@outlook.com>"]
-version = "0.1.0"
+version = "0.2.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

README.md

@@ -1,5 +1,10 @@
 # WannierIO.jl
 
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://io.wannierjl.org/stable)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://io.wannierjl.org/dev)
+[![CI](https://github.com/qiaojunfeng/WannierIO.jl/workflows/CI/badge.svg)](https://github.com/qiaojunfeng/WannierIO.jl/actions?query=workflow%3ACI)
+[![codecov](https://codecov.io/gh/qiaojunfeng/WannierIO.jl/branch/main/graph/badge.svg?token=F7Tl05iVW9)](https://codecov.io/gh/qiaojunfeng/WannierIO.jl)
+
 A Julia package for reading/writing [Wannier90](https://github.com/wannier-developers/wannier90)
 file formats.
 

docs/make.jl

@@ -15,6 +15,7 @@ makedocs(;
             "Wannier90" => "api/w90.md",
             "Volumetric data" => "api/volumetric.md",
             "Quantum ESPRESSO" => "api/qe.md",
+            "Index" => "api/index.md",
         ],
     ],
 )

docs/make_serve.sh

@@ -17,7 +17,10 @@ if [[ $USE_PYTHON == false ]]; then
     # 1. Use [`LiveServer.jl`](https://docs.juliahub.com/LiveServer) to track
     # changes and rebuild docs automatically
     cd "$SCRIPT_DIR/.."
-    julia --project=docs -e 'using WannierIO, Documenter, LiveServer; servedocs()'
+    # use `0.0.0.0` to listen on all interfaces, so that port forward works
+    julia_code="using WannierIO, Documenter, LiveServer; \
+                servedocs(host=\"0.0.0.0\")"
+    julia --project=docs -e "$julia_code"
 else
     # 2. use python's http.server to set up a local server
     cd "$SCRIPT_DIR"

docs/src/api/index.md

@@ -0,0 +1,5 @@
+# Index of all functions and types
+
+```@index
+Modules = [WannierIO]
+```

docs/src/api/util.md

@@ -27,9 +27,16 @@ Modules = [WannierIO]
 Pages   = ["common/type.jl"]
 ```
 
+## Constants
+
+```@autodocs
+Modules = [WannierIO]
+Pages   = ["common/const.jl"]
+```
+
 ## Misc
 
 ```@autodocs
 Modules = [WannierIO]
-Pages   = ["util/header.jl", "util/toml.jl", "util/parser.jl"]
+Pages   = ["util/header.jl", "util/toml.jl", "util/parser.jl", "WannierIO.jl"]
 ```

docs/src/api/w90.md

@@ -14,25 +14,22 @@ CurrentModule = WannierIO
     Currently, the functions are tested on the following platforms:
     - Linux + gfortran 11.2
 
-## Read/write
+## Public API
 
 ```@autodocs
 Modules = [WannierIO]
-Pages   = [
-    "w90/win.jl",
-    "w90/wout.jl",
-    "w90/amn.jl",
-    "w90/mmn.jl",
-    "w90/eig.jl",
-    "w90/spn.jl",
-    "w90/unk.jl",
-    "w90/nnkp.jl",
-    "w90/chk.jl",
-    "w90/tb.jl",
-    "w90/wsvec.jl",
-    "w90/hr.jl",
-    "w90/r.jl",
-    "w90/hh_r.jl",
-    "w90/band.jl",
-]
+Private = false
+Pages   = map(file -> joinpath("w90", file), readdir("../src/w90"))
+```
+
+## Private API
+
+These are some lower-level types/functions that are (probably) less used, thus not exported.
+Of course, you can still use them by prefixing `WannierIO.`, e.g.,
+`WannierIO.read_w90_band_dat(filename)`.
+
+```@autodocs
+Modules = [WannierIO]
+Public = false
+Pages   = map(file -> joinpath("w90", file), readdir("../src/w90"))
 ```

src/WannierIO.jl

@@ -1,4 +1,20 @@
+"""
+`WannierIO.jl`: a package for reading and writing Wannier90 file formats.
+
+---
+
+$(README)
+
+---
+
+Exported functions:
+
+$(EXPORTS)
+
+"""
 module WannierIO
+
+using Printf: @printf, @sprintf
 using DocStringExtensions
 
 include("common/const.jl")

src/common/const.jl

@@ -1,3 +1,6 @@
-# Bohr radius in Angstrom unit
-# This is the default CODATA2006 value in W90 src/constants.F90
+"""
+Bohr radius in Angstrom unit.
+
+This is the default CODATA2006 value in W90 `src/constants.F90`.
+"""
 const Bohr::Float64 = 0.52917721092

src/common/type.jl

@@ -14,10 +14,14 @@ For atom posistions, kpoints, etc.
 """
 const Vec3{T} = SVector{3,T} where {T}
 
-# Vector{Vector} -> Mat3
+"""
+`Vector{Vector}` -> `Mat3`
+"""
 Mat3(A::AbstractVector) = Mat3(reduce(hcat, A))
 
-# Mat3 -> Vec3{Vec3}
+"""
+`Mat3` -> `Vec3{Vec3}`
+"""
 Vec3(A::Mat3) = Vec3(eachcol(A))
 
 """

src/qe/band.jl

@@ -1,9 +1,9 @@
 using LinearAlgebra
 
 """
-    read_qe_band(filename)
+    $(SIGNATURES)
 
-read Quantum ESPRESSO `bands.x` output data file.
+Read Quantum ESPRESSO `bands.x` output data file.
 
 The data file has format
 ```
@@ -59,15 +59,15 @@ function read_qe_band(filename::AbstractString)
 end
 
 """
-    guess_kpath(kpoints)
+    $(SIGNATURES)
 
 Guess high symmetry points from kpoint coordinates.
 
 If there is angle between two consecutive kpoints, then
 it is labeled as a high-symmetry point.
 
 # Arguments
-- `kpoints`: Vector of `Vec3`, in Cartesian coordinates
+- `kpoints`: Vector of `Vector` or `Vec3`, in Cartesian coordinates
 
 # Keyword Arguments
 - `atol`: Absolute tolerance for checking cross product of two vectors
@@ -77,7 +77,7 @@ it is labeled as a high-symmetry point.
 - `symm_point_labels`: Vector of labels of high-symmetry points, for the moment
   it is empty
 """
-function guess_kpath(kpoints::AbstractVector{Vec3}; atol=2e-6)
+function guess_kpath(kpoints::AbstractVector{<:AbstractVector}; atol=2e-6)
     # of course index starts from 1
     symm_point_indices = Vector{Int}()
     symm_point_labels = Vector{String}()

src/qe/xml.jl

@@ -1,7 +1,7 @@
 using EzXML
 
 """
-    read_qe_xml(filename)
+    $(SIGNATURES)
 
 Read atomic structure and band structure from QE's XML output.
 

src/util/fortran.jl

@@ -1,6 +1,6 @@
 
 """
-    isbinary(chars::Vector{UInt8})
+    $(SIGNATURES)
 
 Check if a sequence of chars is binary.
 """
@@ -16,12 +16,11 @@ function isbinary(chars::AbstractVector{UInt8})::Bool
     filter!(x -> x ∉ text_chars, chars)
 
     # display([Char(_) for _ in chars])
-
     return length(chars) > 0
 end
 
 """
-    isbinary(filename::AbstractString)
+    $(SIGNATURES)
 
 Check if the file is in binary format.
 """
@@ -36,7 +35,7 @@ function isbinary(filename::AbstractString)
 end
 
 """
-    parse_float(s::AbstractString)
+    $(SIGNATURES)
 
 Parse a string as `Float64`.
 
@@ -45,7 +44,7 @@ The is capable of parsing Fortran outputs, e.g. `1.0D-10`, to the ordinary `1e-1
 parse_float(s::AbstractString) = parse(Float64, replace(lowercase(strip(s)), "d" => "e"))
 
 """
-    parse_bool(s::AbstractString)
+    $(SIGNATURES)
 
 Parse a string as `bool`.
 
@@ -57,7 +56,7 @@ function parse_bool(s::AbstractString)
 end
 
 """
-    parse_bool(i::Integer)
+    $(SIGNATURES)
 
 Parse an integer as `bool`.
 

src/util/header.jl

@@ -1,4 +1,3 @@
-using Printf: @sprintf
 using Dates: now
 
 """

src/util/lattice.jl

@@ -1,12 +1,12 @@
 """
-    get_recip_lattice(lattice)
+    $(SIGNATURES)
 
 Compute reciprocal lattice from lattice.
 """
 get_recip_lattice(lattice::Mat3) = 2π * inv(lattice)'
 
 """
-    get_lattice(recip_lattice)
+    $(SIGNATURES)
 
 Compute lattice from reciprocal lattice.
 """

src/util/toml.jl

@@ -1,4 +1,6 @@
 """
+    $(SIGNATURES)
+
 Write `kwargs` into `io` as a TOML file.
 
 Do some type conversion before writing.

src/volume/bxsf.jl

@@ -1,13 +1,10 @@
-using Printf: @printf
-using Dates: now
-
 # BXSF format
 # Specification from http://www.xcrysden.org/doc/XSF.html#__toc__14
 
 export read_bxsf, write_bxsf
 
 """
-    read_bxsf(filename::AbstractString)
+    $(SIGNATURES)
 
 Read `bxsf` file.
 
@@ -95,13 +92,7 @@ function read_bxsf(filename::AbstractString)
 end
 
 """
-    write_bxsf(
-        filename::AbstractString,
-        fermi_energy::T,
-        origin::AbstractVector{T},
-        span_vectors::AbstractMatrix{T},
-        E::AbstractArray{T,4},
-    ) where {T<:Real}
+    $(SIGNATURES)
 
 Write `bxsf` file.
 
@@ -126,7 +117,7 @@ function write_bxsf(
 
     # header
     @printf(io, "BEGIN_INFO\n")
-    @printf(io, "  # Created by WannierIO.jl %s\n", string(now()))
+    @printf(io, "  %s\n", default_header())
     @printf(io, "  Fermi Energy: %21.16f\n", fermi_energy)
     @printf(io, "END_INFO\n\n")
 

src/volume/cube.jl

@@ -1,13 +1,10 @@
-using Printf: @printf
-using Dates: now
-
 # Cube format
 # Specification from http://paulbourke.net/dataformats/cube/
 
 export read_cube, write_cube
 
 """
-    read_cube(filename::AbstractString)
+    $(SIGNATURES)
 
 Read `cube` file.
 
@@ -91,7 +88,7 @@ function read_cube(filename::AbstractString)
 end
 
 """
-    write_cube(filename, filename, atom_positions, atom_numbers, origin, span_vectors, W)
+    $(SIGNATURES)
 
 Write `cube` file.
 
@@ -119,7 +116,7 @@ function write_cube(
     io = open(filename, "w")
 
     # header
-    @printf(io, "Created by WannierIO.jl %s\n", string(now()))
+    @printf(io, "%s\n", default_header())
     @printf(io, "outer loop: x, middle loop: y, inner loop: z\n")
 
     # to Bohr

src/volume/xsf.jl

@@ -1,13 +1,10 @@
-using Printf: @printf
-using Dates: now
-
 # XSF format
 # Specification from http://www.xcrysden.org/doc/XSF.html
 
 export read_xsf, write_xsf
 
 """
-    read_xsf(filename::AbstractString)
+    $(SIGNATURES)
 
 Read `xsf` file.
 
@@ -112,7 +109,7 @@ function read_xsf(filename::AbstractString)
 end
 
 """
-    write_xsf(filename, lattice, atom_positions, atom_numbers, origin, span_vectors, W)
+    $(SIGNATURES)
 
 Write `xsf` file.
 
@@ -142,7 +139,7 @@ function write_xsf(
     io = open(filename, "w")
 
     # header
-    @printf(io, "# Created by WannierIO.jl %s\n", string(now()))
+    @printf(io, "%s\n", default_header())
 
     @printf(io, "CRYSTAL\n")
     @printf(io, "PRIMVEC\n")

src/w90/amn.jl

@@ -1,6 +1,3 @@
-using Printf: @printf, @sprintf
-using Dates: now
-
 export read_amn, write_amn
 
 """