Create independent documentation

jmert · Oct 23, 2022 · f57a4ee · f57a4ee
1 parent 4a9df57
commit f57a4ee
Show file tree

Hide file tree

Showing 10 changed files with 98 additions and 68 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -2,17 +2,30 @@
 
 DOCARGS :=
 JULIA ?= julia
+PORT ?= 8000
+
 mkfile_path := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+package_dir := $(realpath $(mkfile_path)..)
 
 export HASTEST
 
-build:
-	cd $(realpath $(mkfile_path)..) && \
-	$(JULIA) --startup-file=no --optimize=0 --project=docs/ \
-		-e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' && \
+default: preview
+
+preview: prepare
+	cd $(package_dir) && \
+		$(JULIA) --startup-file=no --optimize=0 --project=docs/ \
+		-e "using LiveServer; servedocs(port=$(PORT))"
+
+build: prepare
+	cd $(package_dir) && \
 	$(JULIA) --startup-file=no --optimize=0 --project=docs/ \
 		docs/make.jl ${DOCARGS}
 
+prepare:
+	cd $(package_dir) && \
+	$(JULIA) --startup-file=no --optimize=0 --project=docs/ \
+		-e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+
 test: DOCARGS+= --test
 test: build
 	@true

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,7 @@
 [deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Healpix = "5791982e-9993-4c6a-9a71-f887f2b873bc"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
 [compat]

diff --git a/docs/make.jl b/docs/make.jl
@@ -23,7 +23,6 @@ makedocs(
     pages = [
         "Healpix.jl Documentation" => "index.md",
         "Healpix Pixelization" => [
-            "Introduction" => "man/intro.md",
             "Usage" => "man/usage.md",
             "Literature/References" => "man/references.md"
         ],

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,35 @@
+# Healpix.jl Documentation
+
+This library is **not** registered in Julia's
+[General registry](https://github.com/JuliaRegistries/General)
+so the package must be installed either by cloning it directly:
+```julia-repl
+pkg> add https://github.com/jmert/Healpix.jl
+```
+or by making use of my [personal registry](https://github.com/jmert/Registry.jl)
+```julia-repl
+pkg> registry add https://github.com/jmert/Registry.jl
+pkg> add Healpix
+```
+After installing, just load like any other Julia package:
+```julia
+julia> using Healpix
+```
+
+
+## User Manual and Documentation
+```@contents
+Pages = [
+    "man/usage.md",
+    "man/references.md"
+]
+Depth = 1
+```
+
+## Library API Reference
+```@contents
+Pages = [
+    "lib/public.md"
+]
+Depth = 1
+```
diff --git a/docs/src/lib/private.md b/docs/src/lib/private.md
@@ -0,0 +1,6 @@
+# Private API
+
+```@autodocs
+Modules = [Healpix]
+Public = false
+```
diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md
@@ -0,0 +1,6 @@
+# Public API
+
+```@autodocs
+Modules = [Healpix]
+Private = false
+```
diff --git a/docs/src/man/references.md b/docs/src/man/references.md
@@ -1,29 +1,4 @@
-# References
-
-### [BICEP/Keck](@id bib-bicepkeck)
-* J. Tolan. “Testing Inflationary Cosmology with BICEP2 and the Keck Array”.
-  PhD Thesis. Stanford University, Aug. 2014.
-  URL: [http://purl.stanford.edu/sr837cd9569](http://purl.stanford.edu/sr837cd9569)
-
-* The BICEP/Keck Array Collaboration. “BICEP/Keck Array VII: Matrix Based E/B Separation
-  Applied to BICEP2 and the Keck Array”
-  In: *The Astrophysical Journal* 825, 66 (Jul 2016)
-  DOI: [10.3847/0004-637X/825/1/66](http://dx.doi.org/10.3847/0004-637X/825/1/66)
-  arXiv: [1603.05976](https://arxiv.org/abs/1603.05976)
-
-* J. Willmert. “Constraining Inflationary B-modes with the BICEP/Keck Array
-  Telescopes”.
-  PhD Thesis. University of Minnesota, Nov 2019.
-  URL: [http://hdl.handle.net/11299/211821](http://hdl.handle.net/11299/211821)
-
-### [Coordinate systems and conventions](@id bib-coordinates)
-
-* J. P. Hamaker and J. D. Bregman. “Understanding radio polarimetry. III.
-  Interpreting the IAU/IEEE definitions of the Stokes parameters.”
-  In: *Astronomy and Astrophysics, Supplement Series* 117 (May 1996) pp. 161–165.
-  DOI: [10.1051/aas:1996147](https://doi.org/10.1051/aas:1996147)
-
-### [HEALPix](@id bib-healpix)
+# [References](@id bib-healpix)
 
 * K. M. Górski et al. “HEALPix: A Framework for High-Resolution Discretization and Fast
   Analysis of Data Distributed on the Sphere”
@@ -48,12 +23,3 @@
             - \frac{8\phi}{3\pi}
     \end{align*}
     ```
-
-### [Pixel Covariance](@id bib-pixelcovariance)
-
-* M. Tegmark and A. de Oliveira-Costa. “How to measure CMB polarization power spectra
-  without losing information”
-  In: *Physical Review D* 64, 063001 (Sep 2001)
-  DOI: [10.1103/PhysRevD.64.063001](http://dx.doi.org/10.1103/PhysRevD.64.063001)
-  arXiv: [astro-ph/0012120](https://arxiv.org/abs/astro-ph/0012120)
-
diff --git a/docs/src/man/healpix.md → docs/src/man/usage.md b/docs/src/man/healpix.md → docs/src/man/usage.md
@@ -5,18 +5,19 @@ Pages = ["healpix.md"]
 Depth = 2
 ```
 
-The [`Healpix`](@ref) module implements a selection of functions for interacting with
-the **H**ierarchical **E**qual-**A**rea Iso-**L**atitude **Pix**elization (`HEALPix`) as
-described in [Górski et al. (2005)](@ref bib-healpix).
-The emphasis has been on working with pixel index and spherical coordinate conversions
-for the RING-ordered scheme only.
+The [`Healpix`](@ref Healpix.Healpix) module implements a selection of functions for
+interacting with the **H**ierarchical **E**qual-**A**rea Iso-**L**atitude **Pix**elization
+(`HEALPix`) as described in [Górski et al. (2005)](@ref bib-healpix).
+
+The emphasis of this package is on working with pixel index and spherical coordinate
+conversions for the RING-ordered scheme only.
 If a complete `HEALPix` implementation is required, try
 [LibHealpix.jl](https://github.com/mweastwood/LibHealpix.jl) which provides Julia bindings
 to the official C++ library or try using the Python
 [healpy](https://github.com/healpy/healpy) interface via
 [PyCall.jl](https://github.com/JuliaPy/PyCall.jl).
-Additionally, the [Healpix.jl](https://github.com/ziotom78/Healpix.jl) package aims for a
-complete native Julia reimplementation.
+Additionally, a different [Healpix.jl](https://github.com/ziotom78/Healpix.jl) package aims
+for a complete native Julia reimplementation.
 
 ```@raw latex
 \providecommand{\Nside}{N_\mathrm{side}}
@@ -36,9 +37,9 @@ The minimum valid value is ``\Nside = 1``, representing the coarsest pixelizatio
 sphere which can be represented by `HEALPix`.
 The ``\Nside`` then increases by factors of two—denoting ever finer resolutions—with
 the number of pixels covering the sphere being a function of ``\Nside`` alone.
-[`CMB.Healpix.nside2npix`](@ref) returns the number of pixels in a given map:
+[`Healpix.nside2npix`](@ref) returns the number of pixels in a given map:
 ```jldoctest healpix
-julia> using CMB.Healpix
+julia> using Healpix
 
 julia> nside = 4;
 
@@ -47,7 +48,7 @@ julia> nside2npix(nside)
 ```
 Because all pixels are of equal area and the number of pixels is derived from only the
 ``\Nside``, the pixel surface area must be as well.
-For convenience, [`CMB.Healpix.nside2pixarea`](@ref) is provided and is equivalent to the
+For convenience, [`Healpix.nside2pixarea`](@ref) is provided and is equivalent to the
 simple from-scratch calculation (in steradians).
 ```jldoctest healpix
 julia> 4π / nside2npix(nside)
@@ -57,7 +58,7 @@ julia> nside2pixarea(nside)
 0.06544984694978735
 ```
 The number of iso-latitude rings is also a function of only ``\Nside`` and calculated by
-[`CMB.Healpix.nside2nring`](@ref):
+[`Healpix.nside2nring`](@ref):
 ```jldoctest healpix
 julia> nside2nring(nside)
 15
@@ -86,7 +87,7 @@ julia> pix2ringidx.(nside, pix) # Index in ring
 The `HEALPix` grid is symmetric about equator, with the equatorial ring considered part of
 the northern hemisphere by convention.
 Membership as part of the northern or southern hemisphere can be tested with the
-[`CMB.Healpix.isnorth`](@ref) and [`CMB.Healpix.issouth`](@ref) functions, respectively.
+[`Healpix.isnorth`](@ref) and [`Healpix.issouth`](@ref) functions, respectively.
 Pixel 103 is actually the last pixel in the northern hemisphere, so
 ```jldoctest healpix
 julia> isnorth(nside, 103)
@@ -102,8 +103,8 @@ In fact, each hemisphere is further composed of a so-called *polar cap* and *equ
 belt* region of pixels (a property derived from the mathematical details of the `HEALPix`
 grid's definition).
 According to the ring-ordered definition, pixel 0 should be in the polar cap (tested via
-[`CMB.Healpix.iscap`](@ref)), while pixel 103 in the equatorial ring is expected to be
-part of the equitorial belt (tested via [`CMB.Healpix.isequbelt`](@ref)).
+[`Healpix.iscap`](@ref)), while pixel 103 in the equatorial ring is expected to be
+part of the equitorial belt (tested via [`Healpix.isequbelt`](@ref)).
 ```jldoctest healpix
 julia> iscap.(nside, pix)
 (true, false)
@@ -113,9 +114,9 @@ julia> isequbelt.(nside, pix)
 ```
 Membership in a particular hemisphere's polar cap or equatorial belt is accomplished with
 variants inserting `north` and `south` into the function names, i.e. polar caps are
-distinguished by [`CMB.Healpix.isnorthcap`](@ref) and [`CMB.Healpix.issouthcap`](@ref),
+distinguished by [`Healpix.isnorthcap`](@ref) and [`Healpix.issouthcap`](@ref),
 and the halves of the equatorial belt are distinguished by
-[`CMB.Healpix.isnorthequbelt`](@ref) and [`CMB.Healpix.issouthequbelt`](@ref).
+[`Healpix.isnorthequbelt`](@ref) and [`Healpix.issouthequbelt`](@ref).
 ```jldoctest healpix
 julia> pix = (0, 103, 104, 191);
 
@@ -145,19 +146,19 @@ colatitude/azimuth pair of angles on the surface of the sphere identifying the p
 center.
 Colatitude measures the angle (in radians) south of the North Pole, and azimuth measures
 the angle (in radians) east of the Prime Meridian.
-To get the colatitude, use [`CMB.Healpix.pix2theta`](@ref),
+To get the colatitude, use [`Healpix.pix2theta`](@ref),
 ```jldoctest healpix
 julia> pix2theta(nside, 103)
 1.5707963267948966
 ```
-and to get the azimuth, use [`CMB.Healpix.pix2phi`](@ref)
+and to get the azimuth, use [`Healpix.pix2phi`](@ref)
 ```jldoctest healpix
 julia> pix2phi(nside, 103)
 6.086835766330224
 ```
 (both named to follow the mathematical convention that colatitude/azimuth pairs in
 spherical coordinates are the variable pair ``(θ, ϕ)``).
-When the coordinate pair is required, the method [`CMB.Healpix.pix2ang`](@ref) returns a
+When the coordinate pair is required, the method [`Healpix.pix2ang`](@ref) returns a
 2-tuple with the coordinates:
 ```jldoctest healpix
 julia> pix2ang(nside, 103)
@@ -169,7 +170,7 @@ julia> pix2ang(nside, 103) .|> rad2deg
 
 The other common way to represent coordinates on the sphere is via unit vectors.
 The corresponding vector for a given pixel is retrieved with
-[`CMB.Healpix.pix2vec`](@ref).
+[`Healpix.pix2vec`](@ref).
 ```jldoctest healpix; setup = (import StaticArrays: SVector)
 julia> pix2vec(nside, 103)
 3-element SVector{3, Float64} with indices SOneTo(3):
@@ -182,8 +183,8 @@ the positive ``z``-axis passing through the North Pole and the positive ``x``-ax
 passing through the Prime Meridian.
 
 In reverse, converting an arbitrary spherical coordinate to a pixel index is
-accomplished via the [`CMB.Healpix.ang2pix`](@ref) and
-[`CMB.Healpix.vec2pix`](@ref) methods, respectively:
+accomplished via the [`Healpix.ang2pix`](@ref) and
+[`Healpix.vec2pix`](@ref) methods, respectively:
 ```jldoctest healpix
 julia> ang2pix(nside, pix2ang(nside, 103)...)
 103
@@ -198,7 +199,7 @@ As stated earlier, the `HEALPix` ``\Nside`` parameter takes on values which are
 two and by convention of the official `HEALPix` [^1] source is limited to the range
 ``1`` to ``2^{29}``.
 Validity of any `nside` parameter can be checked with the
-[`CMB.Healpix.ishealpixok`](@ref ishealpixok(::Any)) function.
+[`Healpix.ishealpixok`](@ref ishealpixok(::Any)) function.
 ```jldoctest healpix
 julia> ishealpixok(4)
 true
@@ -220,9 +221,9 @@ true
 julia> ishealpixok(4, 192)
 false
 ```
-Variants which throw a [`CMB.Healpix.InvalidNside`](@ref) or
-[`CMB.Healpix.InvalidPixel`](@ref) error are provided by
-[`CMB.Healpix.checkhealpix`](@ref):
+Variants which throw a [`Healpix.InvalidNside`](@ref) or
+[`Healpix.InvalidPixel`](@ref) error are provided by
+[`Healpix.checkhealpix`](@ref):
 ```jldoctest healpix
 julia> checkhealpix(5)
 ERROR: 5 is not a valid Nside parameter (must be power of 2)

diff --git a/test/Project.toml b/test/Project.toml
@@ -1,7 +1,9 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestSetExtensions = "98d24dd4-01ad-11ea-1b02-c9a08f80db04"
 

diff --git a/test/doctests.jl b/test/doctests.jl
@@ -6,8 +6,8 @@ if VERSION >= v"1.6"
     oldlvl = Logging.min_enabled_level(current_logger())
     disable_logging(Logging.Info)
     try
-        DocMeta.setdocmeta!(CMB, :DocTestSetup, :(using CMB); recursive=true)
-        doctest(CMB, testset="Doc Tests")
+        DocMeta.setdocmeta!(Healpix, :DocTestSetup, :(using Healpix); recursive=true)
+        doctest(Healpix, testset="Doc Tests")
     finally
         disable_logging(oldlvl - 1)
     end