Improve docs (#301)

* improve example printing
* add external links to docs
* split doc pages

Author: simonbyrne

docs/examples/02-broadcast.jl

@@ -1,13 +1,12 @@
 import MPI
-
 MPI.Init()
 
 comm = MPI.COMM_WORLD
 N = 5
 root = 0
 
 if MPI.Comm_rank(comm) == root
-    println(" Running on $(MPI.Comm_size(comm)) processes")
+    print(" Running on $(MPI.Comm_size(comm)) processes\n")
 end
 MPI.Barrier(comm)
 
@@ -19,7 +18,7 @@ end
 
 MPI.Bcast!(A, root, comm)
 
-println("rank = $(MPI.Comm_rank(comm)), A = $A")
+print("rank = $(MPI.Comm_rank(comm)), A = $A\n")
 
 if MPI.Comm_rank(comm) == root
     B = Dict("foo" => "bar")
@@ -28,7 +27,7 @@ else
 end
 
 B = MPI.bcast(B, root, comm)
-println("rank = $(MPI.Comm_rank(comm)), B = $B")
+print("rank = $(MPI.Comm_rank(comm)), B = $B\n")
 
 if MPI.Comm_rank(comm) == root
     f = x -> x^2 + 2x - 1
@@ -37,4 +36,4 @@ else
 end
 
 f = MPI.bcast(f, root, comm)
-println("rank = $(MPI.Comm_rank(comm)), f(3) = $(f(3))")
+print("rank = $(MPI.Comm_rank(comm)), f(3) = $(f(3))\n")

docs/examples/03-reduce.jl

@@ -1,5 +1,4 @@
 using MPI
-
 MPI.Init()
 
 comm = MPI.COMM_WORLD

docs/examples/04-sendrecv.jl

@@ -1,5 +1,4 @@
 using MPI
-
 MPI.Init()
 
 comm = MPI.COMM_WORLD
@@ -18,11 +17,11 @@ fill!(send_mesg, Float64(rank))
 
 rreq = MPI.Irecv!(recv_mesg, src,  src+32, comm)
 
-println("$rank: Sending   $rank -> $dst = $send_mesg")
+print("$rank: Sending   $rank -> $dst = $send_mesg\n")
 sreq = MPI.Isend(send_mesg, dst, rank+32, comm)
 
 stats = MPI.Waitall!([rreq, sreq])
 
-println("$rank: Received $src -> $rank = $recv_mesg")
+print("$rank: Received $src -> $rank = $recv_mesg\n")
 
 MPI.Barrier(comm)

docs/make.jl

@@ -14,11 +14,12 @@ isdir(examples_md_dir) || mkdir(examples_md_dir)
 
 for (example_title, example_md) in EXAMPLES
     example_jl = example_md[1:end-2]*"jl"
+    @info "Building $example_md"
     open(joinpath(@__DIR__, "src", example_md), "w") do mdfile
         println(mdfile, "# $example_title")
         println(mdfile)
-        println(mdfile, "`$example_jl`")
         println(mdfile, "```julia")
+        println(mdfile, "# $example_jl")
         write(mdfile, read(joinpath(@__DIR__,example_jl)))
         println(mdfile, "```")
         println(mdfile)
@@ -41,9 +42,13 @@ makedocs(
     modules = [MPI],
     pages = Any[
         "index.md",
-        "installing.md",
+        "installation.md",
         "usage.md",
         "Examples" => EXAMPLES,
+        "Reference" => [
+            "environment.md",
+            "comm.md",
+            ],
         "functions.md",
         ]
 )

docs/src/comm.md

@@ -0,0 +1,28 @@
+# Communicators
+
+An MPI communicator specifies the communication context for a communication operation. In
+particular, it specifies the set of processes which share the context, and assigns each
+each process a unique *rank* (see [`MPI.Comm_rank`](@ref)) taking an integer value in
+`0:n-1`, where `n` is the number of processes in the communicator (see
+[`MPI.Comm_size`](@ref).
+
+## Constants
+
+```@docs
+MPI.COMM_WORLD
+MPI.COMM_SELF
+```
+
+## Functions
+
+```@docs
+MPI.Comm_dup
+MPI.Comm_get_parent
+MPI.Comm_rank
+MPI.Comm_size
+MPI.Comm_spawn
+MPI.Comm_split
+MPI.Comm_split_type
+MPI.Intercomm_merge
+MPI.universe_size
+```

docs/src/environment.md

@@ -0,0 +1,15 @@
+# Environment
+
+## Functions
+
+```@docs
+MPI.Abort
+MPI.Init
+MPI.Initialized
+MPI.Finalize
+MPI.Finalized
+MPI.refcount_inc
+MPI.refcount_dec
+```
+
+

docs/src/functions.md

@@ -6,34 +6,11 @@ Constants like `MPI_SUM` are wrapped as `MPI.SUM`.   Note also that
 arbitrary Julia functions `f(x,y)` can be passed as reduction operations
 to the MPI `Allreduce` and `Reduce` functions.
 
-## Communicators
-Julia interfaces to the Fortran versions of the MPI functions. Since the C and
-Fortran communicators are different, if a C communicator is required (e.g., to
-interface with a C library), this can be achieved with the Fortran to C
-communicator conversion:
-
-```julia
-juliacomm = MPI.COMM_WORLD
-ccomm = MPI.CComm(juliacomm)
-```
-
-## Administrative functions
+## Datatype functions
 
 Julia Function (assuming `import MPI`) | Fortran Function
 ---------------------------------------|--------------------------------------------------------
- [`MPI.Abort`](@ref)                   | [`MPI_Abort`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Abort.3.php)
- [`MPI.Comm_dup`](@ref)                | [`MPI_Comm_dup`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Comm_dup.3.php)
- [`MPI.Comm_free`](@ref)               | [`MPI_Comm_free`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Comm_free.3.php)
- [`MPI.Comm_get_parent`](@ref)         | [`MPI_Comm_get_parent`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Comm_get_parent.3.php)
- [`MPI.Comm_rank`](@ref)               | [`MPI_Comm_rank`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Comm_rank.3.php)
- [`MPI.Comm_size`](@ref)               | [`MPI_Comm_size`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Comm_size.3.php)
- [`MPI.Comm_spawn`](@ref)              | [`MPI_Comm_spawn`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Comm_spawn.3.php)
- [`MPI.Finalize`](@ref)                | [`MPI_Finalize`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Finalize.3.php)
- [`MPI.Finalized`](@ref)               | [`MPI_Finalized`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Finalized.3.php)
  [`MPI.Get_address`](@ref)             | [`MPI_Get_address`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Get_address.3.php)
- [`MPI.Init`](@ref)                    | [`MPI_Init`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Init.3.php)
- [`MPI.Initialized`](@ref)             | [`MPI_Initialized`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Initialized.3.php)
- [`MPI.Intercomm_merge`](@ref)         | [`MPI_Intercomm_merge`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Intercomm_merge.3.php)
  [`MPI.mpitype`](@ref)                 | [`MPI_Type_create_struct`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Type_create_struct.3.php)/[`MPI_Type_commit`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Type_commit.3.php)
 
 !!! note
@@ -43,22 +20,8 @@ Julia Function (assuming `import MPI`) | Fortran Function
 
 
 ```@docs
-MPI.Abort
-MPI.Comm_dup
-MPI.Comm_free
-MPI.Comm_get_parent
-MPI.Comm_rank
-MPI.Comm_size
-MPI.Comm_spawn
-MPI.Finalize
-MPI.Finalized
 MPI.Get_address
-MPI.Init
-MPI.Initialized
-MPI.Intercomm_merge
 MPI.mpitype
-MPI.refcount_inc()
-MPI.refcount_dec()
 ```
 
 ## Point-to-point communication

docs/src/installing.md renamed to docs/src/installation.md

@@ -1,4 +1,4 @@
-# Setup
+# Installation
 
 ## Requirements
 
@@ -10,13 +10,16 @@ MPI.jl requires:
 - A C compiler available via the `mpicc` command: this is required as part of the build
   process to determine the necessary type definitions and constants.
 
-This has been tested with [Open MPI](http://www.open-mpi.org/) and [MPICH](http://www.mpich.org/)).
+This has been tested with:
+- [Open MPI](http://www.open-mpi.org/)
+- [MPICH](http://www.mpich.org/)
+- [Intel MPI](https://software.intel.com/en-us/mpi-library)
 
 ### Windows
 
 MPI.jl requires the [Microsoft MPI (MS-MPI)](https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi) runtime to be installed.
 
-## Installation
+## Building
 
 The MPI.jl package can be installed via `add MPI` in the [Julia package manager](https://docs.julialang.org/en/v1/stdlib/Pkg/index.html). 
 

src/MPI.jl

@@ -26,6 +26,12 @@ primitive type SentinelPtr
 end
 Base.cconvert(::Type{Ptr{T}}, sptr::SentinelPtr) where {T} = reinterpret(Ptr{T}, sptr)
 
+function _doc_external(fname)
+"""
+- `$fname` man page: [OpenMPI](https://www.open-mpi.org/doc/current/man3/$fname.3.php), [MPICH](https://www.mpich.org/static/docs/latest/www3/$fname.html)
+"""
+end    
+
 include(joinpath(@__DIR__, "..", "deps", "deps.jl"))
 include("handle.jl")
 include("info.jl")

src/comm.jl

@@ -1,7 +1,20 @@
 @mpi_handle Comm
 
 const COMM_NULL = _Comm(MPI_COMM_NULL)
+
+"""
+    MPI.COMM_WORLD
+
+A communicator containing all processes with which the local rank can communicate at
+initialization. In a typical "static-process" model, this will be all processes.
+"""
 const COMM_WORLD = _Comm(MPI_COMM_WORLD)
+
+"""
+    MPI.COMM_SELF
+
+A communicator containing only the local process.
+"""
 const COMM_SELF = _Comm(MPI_COMM_SELF)
 
 Comm() = Comm(COMM_NULL.val)
@@ -16,11 +29,17 @@ end
 
 
 """
-    Comm_rank(comm:Comm)
+    Comm_rank(comm::Comm)
 
 The rank of the process in the particular communicator's group.
 
 Returns an integer in the range `0:MPI.Comm_size()-1`.
+
+# See also 
+- [`MPI.Comm_size`](@ref).
+
+# External links
+$(_doc_external("MPI_Comm_rank"))
 """
 function Comm_rank(comm::Comm)
     rank = Ref{Cint}()
@@ -29,16 +48,28 @@ function Comm_rank(comm::Comm)
 end
 
 """
-    Comm_size(comm:Comm)
+    Comm_size(comm::Comm)
 
 The number of processes involved in communicator.
+
+# See also
+- [`MPI.Comm_rank`](@ref).
+
+# External links
+$(_doc_external("MPI_Comm_size"))
 """
 function Comm_size(comm::Comm)
     size = Ref{Cint}()
     @mpichk ccall((:MPI_Comm_size, libmpi), Cint, (MPI_Comm, Ptr{Cint}), comm, size)
     Int(size[])
 end
 
+"""
+    Comm_dup(comm::Comm)
+
+# External links
+$(_doc_external("MPI_Comm_dup"))
+"""
 function Comm_dup(comm::Comm)
     newcomm = Comm()
     @mpichk ccall((:MPI_Comm_dup, libmpi), Cint, (MPI_Comm, Ptr{MPI_Comm}), comm, newcomm)
@@ -47,6 +78,12 @@ function Comm_dup(comm::Comm)
     newcomm
 end
 
+"""
+    Comm_split(comm::Comm, color::Integer, key::Integer)
+
+# External links
+$(_doc_external("MPI_Comm_split"))
+"""
 function Comm_split(comm::Comm, color::Integer, key::Integer)
     newcomm = Comm()
     @mpichk ccall((:MPI_Comm_split, libmpi), Cint,
@@ -56,6 +93,12 @@ function Comm_split(comm::Comm, color::Integer, key::Integer)
     newcomm
 end
 
+"""
+    Comm_split_type(comm::Comm, split_type::Integer, key::Integer; kwargs...)
+
+# External links
+$(_doc_external("MPI_Comm_split_type"))
+"""
 function Comm_split_type(comm::Comm,split_type::Integer,key::Integer; kwargs...)
     newcomm = Comm()
     @mpichk ccall((:MPI_Comm_split_type, libmpi), Cint,
@@ -66,12 +109,24 @@ function Comm_split_type(comm::Comm,split_type::Integer,key::Integer; kwargs...)
     newcomm
 end
 
+"""
+    Comm_get_parent()
+
+# External links
+$(_doc_external("MPI_Comm_get_parent"))
+"""
 function Comm_get_parent()
     comm = Comm()
     @mpichk ccall((:MPI_Comm_get_parent, libmpi), Cint, (Ptr{MPI_Comm},), comm)
     comm
 end
 
+"""
+    Comm_spawn(command, argv::Vector{String}, nprocs::Integer, comm::Comm[, errors::Vector{Cint}]; kwargs...)
+
+# External links
+$(_doc_external("MPI_Comm_spawn"))
+"""
 function Comm_spawn(command::String, argv::Vector{String}, nprocs::Integer,
                     comm::Comm, errors = Vector{Cint}(undef, nprocs); kwargs...)
     intercomm = Comm()
@@ -86,6 +141,12 @@ function Comm_spawn(command::String, argv::Vector{String}, nprocs::Integer,
     return intercomm
 end
 
+"""
+    Intercomm_merge(intercomm::Comm, flag::Bool)
+
+# External links
+$(_doc_external("MPI_Intercomm_merge"))
+"""
 function Intercomm_merge(intercomm::Comm, flag::Bool)
     newcomm = Comm()
     @mpichk ccall((:MPI_Intercomm_merge, libmpi), Cint,