Complete docs

docs/contributing.md

@@ -7,5 +7,49 @@ there is anything missing, please open an [issue](https://github.com/tskit-dev/t
 or [pull request](https://github.com/tskit-dev/tsbrowse/pulls) on Github.
 
 ## Quick start
+### Using a virtual environment
+First, set up a virtual environment:
+```
+$ python3 -m venv tsbrowse_env
+```
+Then, activate the virtual environment:
+```
+$ source tsbrowse_env/bin/activate
+```
+Within the virtual environment, install requirements:
+```
+$ python3 -m pip install -r requirements.txt
+```
 
-TODO! Add information for developers here.
+### Github workflow
+1.    Fork the tsbrowse github repository at https://github.com/tskit-dev/tsbrowse/ to create your own copy of the project.
+
+2.    Clone a local copy:
+```
+$ git clone https://github.com/your-user-name/tsbrowse.git
+$ cd tsbrowse
+$ git remote add upstream https://github.com/tskit-dev/tsbrowse.git
+```
+This creates the directory tsbrowse and connects your repository to the upstream (main project) tsbrowse repository.
+3.    Install pre-commit hooks. These will be executed automatically on every commit, to ensure the code meets development requirements.
+```
+$ pre-commit install
+```
+4.    Run the test suite and make sure tests pass:
+```
+$ python3 -m pytest
+```
+5.    Create a topic branch and add commits:
+```
+$ git fetch upstream
+$ git checkout upstream/main
+$ git checkout -b topic_branch_name
+```
+6.    When you are ready to share your contribution, push changes to your fork:
+```
+$ git push origin branch-name
+```
+7.    Create a [pull request](https://help.github.com/articles/about-pull-requests/) on GitHub.
+
+### Documentation
+Tsbrowse documentation is written in markdown. These files are contained in the docs directory. To build the documentation, run `make` in the `docs` directory.

docs/edges.md

@@ -13,4 +13,4 @@ The bottom panel contains three static histograms which, left to right, summaris
 
 ## Plot controls (sidebar):
 * The `log y-axis` checkbox plots node time on log scale.
-* The checkbox group allows switching between the nodes represented on the Y-axis (parent or child).
+* The checkbox group allows switching between the nodes represented on the Y-axis (parent or child).

docs/index.md

@@ -1,7 +1,24 @@
 (sec_tsbrowse_docs_mainpage)=
 
-# Tsbrowse documentation
+# Tsbrowse documentation  
 
-tsbrowse is an open-source Python package for visualising ARGs in the [tskit](https://tskit.dev/tskit/docs/) tree sequence format.
+This is the documentation for tsbrowse, an open-source Python package for visualising ARGs in the [tskit](https://tskit.dev/tskit/docs/) tree sequence format.  
 
-TODO! Add links to other pages
+## Contents  
+### Getting started  
+This section includes an introduction to tsbrowse, amd notes on how to install and use the app.  
+    [Introduction](intro.md)  
+    [Installing tsbrowse](install.md)  
+### Pages  
+This section provides an overview of the various pages displayed in the webapp.  
+    [Overview](overview.md)  
+    [Tables](tables.md)  
+    [Mutations](mutations.md)  
+    [Edges](edges.md)  
+    [Nodes](nodes.md)  
+    [Trees](trees.md)  
+### Extras  
+Feedback and bug reports are welcome. This section contains information on contributing and engaging with the tskit community.  
+    [Contributing](contributing.md)  
+    [Changelog](CHANGELOG.md)  
+    [Community](https://tskit.dev/community/)  

docs/install.md

@@ -1,5 +1,24 @@
 (install)=
 
 # Installing tsbrowse
+```
+python3 -m pip install tsbrowse
+```
 
-TODO! Add information on install and deps, then link to intro
+To install the development version:
+```
+python3 -m pip install git+https://github.com/tskit-dev/tsbrowse
+```
+Please also see the documentation on [Contributing](contributing.md).
+
+# Dependencies
+|Package |Minimum supported version|
+|-----|--------|
+|Datashader|0.16.3|
+|Panel|1.5.2|
+|Tszip||
+|Tskit||
+|Daiquiri||
+|Hvplot||
+
+For an introduction to tsbrowse, see [Introduction](intro.md)

docs/intro.md

@@ -1,8 +1,31 @@
 (sec_intro)=
 
 # Introduction to tsbrowse
+Tsbrowse is an open-source Python web-app intended as a genome browser for ARGs. It provides interactive visual summaries of the fundamental components of an ARG, i.e. the mutations, nodes, edges and trees it encodes. Tsbrowse operates on ARGs encoded as succinct tree sequences (see [tskit](https://tskit.dev/tskit/docs/stable/introduction.html)). It can be used to inspect biobank-scale ARGs without requiring data uploads to a server.
 
-# Data Model
+## Data Model
+The foundation of tsbrowse is the [tskit data model](https://tskit.dev/tskit/docs/stable/data-model.html), which is a generalised ARG representation. Tsbrowse can therefore be applied to ARGs inferred using widely-used methods including [tsinfer](https://tskit.dev/tsinfer/docs/stable/), [Relate](https://myersgroup.github.io/relate/), [ARG-Needle](https://palamaralab.github.io/software/argneedle/) and [SINGER](https://github.com/popgenmethods/SINGER). Tsbrowse augments the underlying tree sequence tables with additional columns to create a compressed `.tsbrowse` file, containing all necessary semantic metadata required for automatic visualisation with the [Holoviz](https://holoviz.org/) ecosystem. 
 
-# How to
-TODO! Add a quick start guide with example tree sequences
+## How to
+Consider an example tree sequence simulated with msprime:
+```
+def make_sweep_ts(n, Ne, L, rho=1e-8, mu=1e-8):
+    sweep_model = msprime.SweepGenicSelection(
+        position=L/2, start_frequency=0.0001, end_frequency=0.9999, s=0.25, dt=1e-6)
+        models = [sweep_model, msprime.StandardCoalescent()]
+    ts = msprime.sim_ancestry(
+        n, model=models, population_size=Ne, sequence_length=L, recombination_rate=rho, random_seed=1234)
+    return msprime.sim_mutations(ts, rate=mu, random_seed=4321)
+
+sim_ts = make_sweep_ts(300, Ne=10_000, L=5_000_000, mu=1e-8)
+sim_ts.dump("example.trees")
+```
+To run tsbrowse on this tree sequence, we first run the preprocessing step.
+```
+python -m tsbrowse preprocess example.trees
+```
+This creates a `.tsbrowse` file in the same directory as the input tree sequence.
+We can then run the serve step to view the app in a web browser:
+```
+python -m tsbrowse serve example.tsbrowse --port 8080
+```

docs/trees.md

@@ -2,4 +2,8 @@
 
 # Trees page
 
-![Trees Page](tsbrowse:example.tsbrowse:trees)
+![Trees Page](tsbrowse:example.tsbrowse:trees)
+A tree sequence generally consists of multiple highly correlated genetic genealogies along the sequence, referred to as trees. This page summarises the individual trees in a tree sequence. The histograms show the distribution of various aspects of the trees, including the number of sites and mutations in each tree, the genomic span (i.e., the length of sequence the tree spans), the total branch length (i.e., the total sum of branch lengths over all samples in the tree, in time units), and the arity (i.e., the number of children nodes in the tree have).
+
+## Plot controls (sidebar):
+* The `log y-axis` checkbox plots the number of trees on the log scale.