Merge pull request #4 from LCSB-BioCore/mk-docs

add the documentation

.github/workflows/docs.yml

+# ref: https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#GitHub-Actions-1
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  release:
+    types: [published, created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: 1.5
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

README.md

 # SBML.jl
 
-This is a simple wrap of some of the libSBML functionality.
+| Build status | Documentation |
+|:---:|:---:|
+| ![CI](https://github.com/LCSB-BioCore/SBML.jl/workflows/CI/badge.svg?branch=develop) | [![doc](https://img.shields.io/badge/docs-stable-blue)](https://lcsb-biocore.github.io/SBML.jl/stable/) [![doc](https://img.shields.io/badge/docs-dev-blue)](https://lcsb-biocore.github.io/SBML.jl/dev/) |
 
-Current status is "under development", something works, more wrapped stuff will
-be added by need.
+
+This is a simple wrap of some of the libSBML functionality, mainly the model loading for purposes of COBRA analysis methods.
+
+Other functionality will be added as needed. Feel free to submit a PR that increases the loading "coverage".
 
 ## Usage
 
@@ -11,7 +15,7 @@ be added by need.
 using SBML
 m = readSBML("myModel.xml")
 
-# m is now a Model with
+# m is now a Model structure with:
 m.reactions
 m.species
 m.compartments

docs/make.jl

@@ -2,7 +2,9 @@ using Documenter, SBML
 
 makedocs(modules = [SBML],
     clean = false,
-    format = Documenter.HTML(prettyurls = !("local" in ARGS)),
+    format = Documenter.HTML(
+        prettyurls = !("local" in ARGS),
+        canonical = "https://lcsb-biocore.github.io/DistributedData.jl/stable/"),
     sitename = "SBML.jl",
     authors = "The developers of SBML.jl",
     linkcheck = !("skiplinks" in ARGS),
@@ -16,5 +18,5 @@ deploydocs(
     target = "build",
     branch = "gh-pages",
     devbranch = "develop",
-    versions = "stable" => "v^",
+    push_preview = true
 )

src/structs.jl

 
 """
-Part of a measurement unit definition that corresponds to the SBML definition of `Unit`. For example, "per square megahour", Mh^(-2), is written as:
+Part of a measurement unit definition that corresponds to the SBML definition
+of `Unit`. For example, the unit "per square megahour", Mh^(-2), is written as:
 
-    UnitPart("second", # base unit of time
-             -2, # exponent, says "per square"
-             6, # scale in powers of 10, says "mega"
-             1/3600) # second-to-hour multiplier
+    UnitPart("second",  # base SI unit, this says we are measuring time
+             -2,        # exponent, says "per square"
+             6,         # log-10 scale of the unit, says "mega"
+             1/3600)    # second-to-hour multiplier
+
+Compound units (such as "volt-amperes" and "dozens of yards per ounce") are
+built from multiple `UnitPart`s; see the definition of field `units` in
+[`Model`](@ref).
 """
 struct UnitPart
     kind::String
@@ -17,8 +22,9 @@ end
 
 """
 Reaction with stoichiometry that assigns reactants and products their relative
-consumption/production rates, lower/upper bounds (in tuples with unit names),
-and objective coefficient.
+consumption/production rates (accessible in field `stoichiometry`), lower/upper
+bounds (in tuples `lb` and `ub`, with unit names), and objective coefficient
+(`oc`).
 """
 struct Reaction
     stoichiometry::Dict{String,Float64}
@@ -29,7 +35,8 @@ struct Reaction
 end
 
 """
-Species metadata -- human-readable name and compartment identifier
+Species metadata -- contains a human-readable `name`, and a `compartment`
+identifier
 """
 struct Species
     name::String
@@ -38,8 +45,9 @@ struct Species
 end
 
 """
-Structure that collects the model-related data. Dictionaries are indexed by
-identifiers of the corresponding objects.
+Structure that collects the model-related data. Contains `units`,
+`compartments`, `species` and `reactions`. The contained dictionaries are
+indexed by identifiers of the corresponding objects.
 """
 struct Model
     units::Dict{String,Vector{UnitPart}}