Add tutorial.

.gitignore

@@ -1 +1,3 @@
 docs/_build
+__pycache__
+.coverage

docs/_config.yml

@@ -5,7 +5,6 @@ title: Demes Specification
 author: PopSim Consortium
 copyright: "2021"
 only_build_toc_files: true
-# logo: logo.png
 
 execute:
   execute_notebooks: cache
@@ -15,6 +14,10 @@ repository:
   branch: main
   path_to_book: docs
 
+launch_buttons:
+  # Disable binder launch button on pages with python code.
+  binderhub_url: ""
+
 html:
   use_issues_button: true
   use_repository_button: true
@@ -30,10 +33,5 @@ sphinx:
     - sphinx-jsonschema
 
     config:
-      myst_enable_extensions:
-      - colon_fence
-      - deflist
       todo_include_todos: true
-      intersphinx_mapping:
-        demes: ["https://popsim-consortium.github.io/demes-docs/main/", null]
       nitpicky: true

docs/_static/custom.css

@@ -1,17 +1,51 @@
 /*
- * RTD adds horizontal scrollbars to tables, making the tables very difficult
- * to read. The workaround here will wrap lines within table cells.
- * https://github.com/readthedocs/sphinx_rtd_theme/issues/117
+ * Some custom admonitions.
  */
-@media screen and (min-width: 767px) {
 
-   .wy-table-responsive table td {
-      /* !important prevents the common CSS stylesheets from overriding
-         this as on RTD they are loaded after this stylesheet */
-      white-space: normal !important;
-   }
+/* Variables */
+:root {
+  --tip-title-color: #fff6dd;
+  --tip-border-color: #ffc107;
+  --seealso-title-color: rgba(40,167,70,0.1);
+  --seealso-icon-color: #28a745;
+}
+
+/* exercise */
+div.exercise {
+  border-color: var(--tip-border-color);
+}
+div.exercise p.admonition-title {
+  background-color: var(--tip-title-color);
+}
+div.exercise p.admonition-title::before {
+  /*
+   * Use an icon from fontawesome. Nagivate to https://fontawesome.com/
+   * and copy the unicode code for the desired icon.
+   */
+  color: var(--tip-border-color);
+  content: "\f11c";
+}
 
-   .wy-table-responsive {
-      overflow: visible !important;
-   }
+/* question */
+div.question {
+  border-color: var(--tip-border-color);
+}
+div.question p.admonition-title {
+  background-color: var(--tip-title-color);
+}
+div.question p.admonition-title::before {
+  color: var(--tip-border-color);
+  content: "\f059";
+}
+
+/* answer */
+div.answer {
+  border-color: var(--seealso-icon-color);
+}
+div.answer p.admonition-title {
+  background-color: var(--seealso-title-color);
+}
+div.answer p.admonition-title::before {
+  color: var(--seealso-icon-color);
+  content: "\f064";
 }

docs/introduction.md

@@ -1,17 +1,18 @@
 (sec_intro)=
 # Introduction
 
-## What is the Demes Specification?
+## What is the Demes specification?
 
-The Demes Specification is a concrete proposal to standardise:
+The Demes specification is a concrete proposal to standardise:
 
  - {ref}`how computational biologists write down demographic models <sec_tutorial>`, and
  - {ref}`how those models should be interpreted by software <sec_spec>`.
 
 
 ## Why is it necessary?
 
-It can be tedious and error prone to write down a demographic model for
+It can be tedious and [error prone](https://doi.org/10.1016/j.ajhg.2020.08.017)
+to write down a demographic model for
 use with population genetics software, such as simulators. Moreover,
 genetics software use many different and often incompatible input formats
 for describing demographic models. So a user may be forced to rewrite

docs/reference.rst

@@ -6,15 +6,22 @@
 Reference
 =========
 
-The structure of ``demes``' data model is formally defined using
+.. warning::
+
+   Demes is a work in progress and some details of this reference are
+   currently incomplete, or incorrect, due to recent changes and
+   discussions by the Demes authors. Please bear with us as we update
+   the reference documentation.
+
+The structure of the Demes data model is formally defined using
 `JSON schema <https://json-schema.org/>`_ and rendered below as a table.
 A machine readable version of the schema (from which this table was generated)
 can be found in the ``demes-specification.yaml`` file of the 
 `demes-spec repository <https://github.com/popsim-consortium/demes-spec>`_.
 
 .. note::
 
- The formal requirements of ``demes``' data model impose inter-property
+ The formal requirements of the Demes data model impose inter-property
  constraints that cannot be described using JSON schema alone.
  These additional conditions are described throughout this document
  using the language *must* or *must not*.