Merge pull request #58 from MineralsCloud:docs

Add docs
MineralsCloud · Jul 5, 2021 · e9dfa18 · e9dfa18
2 parents 7905af7 + 5ec302d
commit e9dfa18
Show file tree

Hide file tree

Showing 10 changed files with 172 additions and 47 deletions.
diff --git a/Project.toml b/Project.toml
@@ -7,13 +7,11 @@ version = "0.1.1"
 CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298"
 CrystallographyBase = "93b1d1cd-a8ea-4aa5-adb1-b2407ea0ba8d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-Spglib = "f761d5c5-86db-4880-b97f-9680a7cccfb5"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
 [compat]
 CoordinateTransformations = "0.5, 0.6"
 CrystallographyBase = "0.1"
-Spglib = "0.1, 0.2"
 StaticArrays = "0.8.3, 0.9, 0.10, 0.11, 0.12, 1"
 julia = "1"
 

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,3 +1,4 @@
 [deps]
-Crystallography = "06308cd2-f292-494b-9308-80930bf85278"
+Crystallography = "3bff3928-7a76-11e9-2089-d112443085a5"
+CrystallographyBase = "93b1d1cd-a8ea-4aa5-adb1-b2407ea0ba8d"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,10 +1,11 @@
 using Crystallography
+using CrystallographyBase
 using Documenter
 
 DocMeta.setdocmeta!(Crystallography, :DocTestSetup, :(using Crystallography); recursive=true)
 
 makedocs(;
-    modules=[Crystallography],
+    modules=[Crystallography,CrystallographyBase],
     authors="Qi Zhang <[email protected]>",
     repo="https://github.com/MineralsCloud/Crystallography.jl/blob/{commit}{path}#{line}",
     sitename="Crystallography.jl",
@@ -15,10 +16,9 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
-        "Manual" => Any["Installation"=>"install.md", "Development"=>"develop.md"],
+        "Manual" => Any["Installation"=>"installation.md", "Development"=>"develop.md"],
         "API by modules" => Any[
-            "`Crystallography` module"=>"Crystallography.md",
-            "`Crystallography.Symmetry` module"=>"Symmetry.md",
+            "`Crystallography` module"=>"api.md",
         ],
     ],
 )

diff --git a/docs/src/Crystallography.md b/docs/src/Crystallography.md
diff --git a/docs/src/Symmetry.md b/docs/src/Symmetry.md
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -0,0 +1,86 @@
+```@meta
+CurrentModule = CrystallographyBase
+```
+
+# API
+
+```@contents
+Pages = ["api.md"]
+Depth = 3
+```
+
+### Lattice
+
+```@docs
+CrystalSystem
+Triclinic
+Monoclinic
+Orthorhombic
+Tetragonal
+Cubic
+Trigonal
+Hexagonal
+Centering
+BaseCentering
+Primitive
+BodyCentering
+FaceCentering
+RhombohedralCentering
+BaseCentering
+Bravais
+Lattice
+centering
+crystalsystem
+basis_vectors
+cellparameters
+supercell
+```
+
+### Reciprocal space
+
+Note that we take ``2pi`` as ``1``, not the solid-state physics convention.
+
+```@docs
+ReciprocalPoint
+ReciprocalLattice
+inv
+reciprocal_mesh
+coordinates
+weights
+```
+
+### Miller and Miller–Bravais indices
+
+```@docs
+Miller
+MillerBravais
+ReciprocalMiller
+ReciprocalMillerBravais
+family
+@m_str
+```
+
+### Metric tensor
+
+```@docs
+MetricTensor
+directioncosine
+directionangle
+distance
+interplanar_spacing
+```
+
+### Transformations
+
+```@docs
+CartesianFromFractional
+FractionalFromCartesian
+PrimitiveFromStandardized
+StandardizedFromPrimitive
+```
+
+### Others
+
+```@docs
+cellvolume
+```
diff --git a/docs/src/develop.md b/docs/src/develop.md
@@ -1,23 +1,20 @@
-# How to develop this package by yourself
+# How to contribute
 
 ## Download the project
 
-Similar to what we have mentioned in section "[Installation](@ref)", instead of running
+Similar to section "[Installation](@ref)", run
 
 ```julia
-julia> Pkg.add(PackageSpec(url="https://github.com/MineralsCloud/Crystallography.jl.git"))
-```
-
-run
+julia> using Pkg
 
-```julia
-julia> Pkg.dev(PackageSpec(url="https://github.com/MineralsCloud/Crystallography.jl.git"))
+julia> pkg"dev Crystallography"
 ```
 
+in Julia REPL.
+
 Then the package will be cloned to your local machine at a path. On macOS, by default is
 located at `~/.julia/dev/Crystallography` unless you modify the `JULIA_DEPOT_PATH`
-environment variable. (See [Julia's official
-documentation](http://docs.julialang.org/en/v1/manual/environment-variables/#JULIA_DEPOT_PATH-1)
+environment variable. (See [Julia's official documentation](http://docs.julialang.org/en/v1/manual/environment-variables/#JULIA_DEPOT_PATH-1)
 on how to do this.) In the following text, we will call it `PKGROOT`.
 
 ## [Instantiate the project](@id instantiating)
@@ -30,6 +27,10 @@ julia> using Pkg; Pkg.instantiate()
 
 ## How to build docs
 
+Usually, the up-to-state doc is available in
+[here](https://mineralscloud.github.io/Crystallography.jl/dev/), but there are cases
+where users need to build the doc themselves.
+
 After [instantiating](@ref) the project, go to `PKGROOT`, run (without the `$` prompt)
 
 ```bash

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -6,9 +6,41 @@ CurrentModule = Crystallography
 
 Documentation for [Crystallography](https://github.com/MineralsCloud/Crystallography.jl).
 
-```@index
+## Package Features
+
+Provides some types and methods for crystallography calculations.
+
+See the [Index](@ref main-index) for the complete list of documented functions
+and types.
+
+The code is [hosted on GitHub](https://github.com/MineralsCloud/Crystallography.jl),
+with some continuous integration services to test its validity.
+
+This repository is created and maintained by [singularitti](https://github.com/singularitti).
+You are very welcome to contribute.
+
+## Compatibility
+
+- [Julia version: `v1.3.0` to `v1.6.1`](https://julialang.org/downloads/)
+- Dependencies:
+  - [`CoordinateTransformations.jl`](https://github.com/JuliaGeometry/CoordinateTransformations.jl) `v0.5.1` and above
+  - [`CrystallographyBase.jl`](https://github.com/MineralsCloud/CrystallographyBase.jl) `v0.1.0` and above
+  - [`StaticArrays.jl`](https://github.com/JuliaArrays/StaticArrays.jl) `v0.8.3` and above
+- OS: macOS, Linux, Windows, and FreeBSD
+- Architecture: x86, x64, ARM
+
+## Manual Outline
+
+```@contents
+Pages = [
+    "installation.md",
+    "develop.md",
+    "api.md",
+]
+Depth = 3
 ```
 
-```@autodocs
-Modules = [Crystallography]
+## [Index](@id main-index)
+
+```@index
 ```
diff --git a/docs/src/install.md → docs/src/installation.md b/docs/src/install.md → docs/src/installation.md
@@ -1,16 +1,39 @@
 # Installation
 
+```@contents
+Pages = ["installation.md"]
+Depth = 3
+```
+
 To install this package, first, you need to install a `julia` executable from
-[its official website](https://julialang.org/downloads/). Version `v1.0.0` and
+[its official website](https://julialang.org/downloads/). Version `v1.3.0` and
 above is required. This package may not work on `v0.7` and below.
 
+## Installing Julia
+
+### on macOS
+
 If you are using a Mac, and have [Homebrew](https://brew.sh) installed, open
 `Terminal.app` and type:
 
 ```shell
 brew cask install julia
 ```
 
+### on Linux
+
+On Linux, the best way to install Julia is to use the Generic Linux Binaries. The
+[JILL](https://github.com/abelsiqueira/jill) script does this for you. Just run
+
+```shell
+bash -ci "$(curl -fsSL https://raw.githubusercontent.com/abelsiqueira/jill/master/jill.sh)"
+```
+
+installs Julia into `$HOME/.local/bin`. This script also has a Python version,
+[JILL.py](https://github.com/johnnychen94/jill.py). It can also be used on macOS.
+
+## Installing the package
+
 Now I am using [macOS](https://en.wikipedia.org/wiki/MacOS) as a standard
 platform to explain the following steps:
 
@@ -21,7 +44,7 @@ platform to explain the following steps:
    ```julia
    julia> using Pkg; Pkg.update()
 
-   julia> Pkg.add(PackageSpec(url="https://github.com/MineralsCloud/Crystallography.jl.git"))
+   julia> Pkg.add("Crystallography")
    ```
 
    and wait for its finish.

diff --git a/src/Crystallography.jl b/src/Crystallography.jl
@@ -41,8 +41,8 @@ using CrystallographyBase:
     ReciprocalLattice,
     Miller,
     MillerBravais,
-    RealSpace,
-    ReciprocalSpace,
+    ReciprocalMiller,
+    ReciprocalMillerBravais,
     FractionalFromCartesian,
     CartesianFromFractional,
     FractionalToCartesian,
@@ -62,9 +62,9 @@ using CrystallographyBase:
     reciprocal_mesh,
     coordinates,
     weights,
+    family,
     cellvolume,
-    @m_str,
-    @mb_str
+    @m_str
 
 export CrystalSystem,
     Triclinic,
@@ -107,8 +107,8 @@ export CrystalSystem,
     ReciprocalLattice,
     Miller,
     MillerBravais,
-    RealSpace,
-    ReciprocalSpace,
+    ReciprocalMiller,
+    ReciprocalMillerBravais,
     FractionalFromCartesian,
     CartesianFromFractional,
     FractionalToCartesian,
@@ -128,10 +128,10 @@ export centering,
     reciprocal_mesh,
     coordinates,
     weights,
+    family,
     cellvolume,
-    @m_str,
-    @mb_str
+    @m_str
 
-include("Symmetry.jl")
+# include("Symmetry.jl")
 
 end