More documentation

Author: MilesCranmer

docs/Project.toml

@@ -1,3 +1,2 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DynamicQuantities = "06fc5a27-2a28-4c7c-a15d-362465fb6821"

docs/make.jl

@@ -1,4 +1,5 @@
 using DynamicQuantities
+import DynamicQuantities.Units
 using Documenter
 
 DocMeta.setdocmeta!(DynamicQuantities, :DocTestSetup, :(using DynamicQuantities); recursive=true)
@@ -26,7 +27,7 @@ open(dirname(@__FILE__) * "/src/index.md", "w") do io
 end
 
 makedocs(;
-    modules=[DynamicQuantities],
+    modules=[DynamicQuantities, DynamicQuantities.Units],
     authors="MilesCranmer <[email protected]> and contributors",
     repo="https://github.com/SymbolicML/DynamicQuantities.jl/blob/{commit}{path}#{line}",
     sitename="DynamicQuantities.jl",

docs/src/api.md

@@ -1,15 +1,87 @@
-```@meta
-CurrentModule = DynamicQuantities
+# Usage
+
+## Types
+
+```@docs
+Quantity
+Dimensions
 ```
 
-# API Reference
+## Utilities
+
+The two main general utilities for working
+with quantities are `ustrip` and `dimension`:
 
-API Reference for [DynamicQuantities](https://github.com/SymbolicML/DynamicQuantities.jl).
+```@docs
+ustrip
+dimension
+```
+
+Utility functions to extract specific dimensions are as follows:
 
-```@index
+```@docs
+ulength
+umass
+utime
+ucurrent
+utemperature
+uluminosity
+uamount
 ```
 
 ```@autodocs
 Modules = [DynamicQuantities]
-Order   = [:type, :function]
-```
+Pages   = ["utils.jl"]
+Filter  = t -> !(t in [ustrip, dimension, ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount])
+```
+
+## Units
+
+The two main functions for working with units are `uparse` and `u_str`:
+
+```@docs
+@u_str
+uparse
+```
+
+The base SI units are as follows.
+Instead of calling directly, it is recommended to access them via
+the `@u_str` macro, which evaluates the expression
+in a namespace with all the units available.
+
+```@docs
+Units.m
+Units.g
+Units.s
+Units.A
+Units.K
+Units.cd
+Units.mol
+```
+
+Several derived SI units are available as well:
+
+```@docs
+Units.Hz
+Units.N
+Units.Pa
+Units.J
+Units.W
+Units.C
+Units.V
+Units.F
+Units.Ω
+Units.T
+Units.L
+Units.bar
+```
+
+## Internals
+
+### FixedRational
+
+```@docs
+DynamicQuantities.FixedRational
+DynamicQuantities.denom
+```
+

src/types.jl

@@ -2,11 +2,13 @@ const DEFAULT_DIM_TYPE = FixedRational{Int32, 2^4 * 3^2 * 5^2 * 7}
 const DEFAULT_VALUE_TYPE = Float64
 
 """
-    Dimensions
+    Dimensions{R}
 
 A type representing the dimensions of a quantity, with each
 field giving the power of the corresponding dimension. For
 example, the dimensions of velocity are `Dimensions(length=1, time=-1)`.
+Each of the 7 dimensions are stored using the type `R`,
+which is by default a rational number.
 
 # Fields
 
@@ -56,9 +58,9 @@ const DIMENSION_SYNONYMS = (:m, :kg, :s, :A, :K, :cd, :mol)
 const SYNONYM_MAPPING = NamedTuple(DIMENSION_NAMES .=> DIMENSION_SYNONYMS)
 
 """
-    Quantity{T}
+    Quantity{T,R}
 
-Physical quantity with value `value` of type `T` and dimensions `dimensions`.
+Physical quantity with value `value` of type `T` and dimensions `dimensions` of type `Dimensions{R}`.
 For example, the velocity of an object with mass 1 kg and velocity
 2 m/s is `Quantity(2, mass=1, length=1, time=-1)`.
 You should access these fields with `ustrip(q)`, and `dimensions(q)`.