Merge pull request #345 from mcveanlab/doc-improvements

Doc improvements

Author: jeromekelleher

CHANGELOG.rst

@@ -1,5 +1,5 @@
 --------------------
-[0.0.0] - 2019-XX-XX
+[0.1.0] - 2019-12-18
 --------------------
 
 Initial release.

docs/_ext/speciescatalog.py

@@ -45,86 +45,46 @@ def get_target(self, tid):
         self.state.document.note_explicit_target(target)
         return target
 
-    def species_summary_table(self, species):
-        table = nodes.table()
-        tgroup = nodes.tgroup(cols=2)
-        colspec = nodes.colspec(colwidth=1)
-        tgroup.append(colspec)
-        colspec = nodes.colspec(colwidth=1)
-        tgroup.append(colspec)
-        colspec = nodes.colspec(colwidth=1)
-        tgroup.append(colspec)
-
-        table += tgroup
-
-        data = [
-            ("id", species.id, ""),
-            ("name", species.name, ""),
-            ("generation_time", species.generation_time,
-                "TODO: Notes for generation_time"),
-            ("population_size", species.population_size,
-                "TODO: Notes for population_size"),
-        ]
-
-        rows = []
-        for row_data in data:
-            row = nodes.row()
-            rows.append(row)
-            for entry_data in row_data:
-                entry = nodes.entry()
-                entry += nodes.paragraph(text=entry_data)
-                row += entry
+    def make_field_list(self, data):
 
-        tbody = nodes.tbody()
-        tbody.extend(rows)
-        tgroup += tbody
+        field_list = nodes.field_list()
+        for name, text, citation in data:
+            field = nodes.field()
+            field_name = nodes.field_name(text=name)
+            field_body = nodes.field_body()
+            para = nodes.paragraph(text=text)
 
-        return table
+            if citation is not None:
+                text = f" ({citation.author}, {citation.year})"
+                para += nodes.reference(
+                    internal=False, refuri=citation.doi, text=text)
 
-    def model_table(self, model):
-        table = nodes.table()
-        tgroup = nodes.tgroup(cols=2)
+            field_body += para
+            field += field_name
+            field += field_body
+            field_list += field
 
-        colspec = nodes.colspec(colwidth=1)
-        tgroup.append(colspec)
-        colspec = nodes.colspec(colwidth=1)
-        tgroup.append(colspec)
+        return field_list
 
-        table += tgroup
-
-        rows = []
-        row = nodes.row()
-        rows.append(row)
-        entry = nodes.entry()
-        entry += nodes.paragraph(text="ID")
-        row += entry
-        entry = nodes.entry()
-        entry += nodes.paragraph(text=model.id)
-        row += entry
-
-        row = nodes.row()
-        rows.append(row)
-        entry = nodes.entry()
-        entry += nodes.paragraph(text="Description")
-        row += entry
-        entry = nodes.entry()
-        entry += nodes.paragraph(text=model.description)
-        row += entry
-
-        row = nodes.row()
-        rows.append(row)
-        entry = nodes.entry()
-        entry += nodes.paragraph(text="Num populations")
-        row += entry
-        entry = nodes.entry()
-        entry += nodes.paragraph(text=model.num_populations)
-        row += entry
-
-        tbody = nodes.tbody()
-        tbody.extend(rows)
-        tgroup += tbody
+    def species_summary(self, species):
+        data = [
+            ("ID", species.id, None),
+            ("Name", species.name, None),
+            ("Common name", species.common_name, None),
+            ("Generation time", species.generation_time,
+                species.generation_time_citations[0]),
+            ("Population size", species.population_size,
+                species.population_size_citations[0]),
+        ]
+        return self.make_field_list(data)
 
-        return table
+    def model_summary(self, model):
+        data = [
+            ("ID", model.id, None),
+            ("Description", model.description, None),
+            ("Num populations", model.num_populations, None),
+        ]
+        return self.make_field_list(data)
 
     def citation_list(self, citable):
         bullet_list = nodes.bullet_list()
@@ -411,7 +371,7 @@ def model_section(self, species, model):
         section += nodes.title(text=model.description)
         section += nodes.paragraph(text=model.long_description)
         section += nodes.rubric(text="Details")
-        section += self.model_table(model)
+        section += self.model_summary(model)
         section += nodes.rubric(text="Populations")
         section += self.population_table(model)
         section += nodes.rubric(text="Citations")
@@ -427,7 +387,7 @@ def run(self):
         species_target = self.get_target(sid)
         section = nodes.section(ids=[sid], names=[sid])
         section += nodes.title(text=species.name)
-        section += self.species_summary_table(species)
+        section += self.species_summary(species)
 
         genome_section = nodes.section(ids=[f"sec_catalog_{species.id}_genome"])
         genome_section += nodes.title(text="Genome")

docs/catalog.rst

@@ -29,7 +29,7 @@ and saves the output to a file called ``test.trees``:
 
 .. code-block:: console
 
-    $ stdpopsim HomSap -c chr22 -o test.trees -g HapmapII_GRCh37  --model ooa_3 2 2 2
+    $ stdpopsim HomSap -c chr22 -o test.trees -g HapMapII_GRCh37 --model OutOfAfrica_3G09 2 2 2
 
 (To learn more about using ``stdpopsim`` via the command-line, read our :ref:`sec_tutorial`
 about it.)

docs/docutils.conf

@@ -0,0 +1,5 @@
+# This is used to make sure that we don't split lines when field names 
+# are long in the speciescatalog extension. See 
+# https://stackoverflow.com/questions/13029207/overriding-the-default-field-name-limit-in-sphinx-docutils
+[html4css1 writer]
+field_name_limit: 40

docs/installation.rst

@@ -4,6 +4,89 @@
 Installation
 ============
 
+There are two basic options for installing ``stdpopsim`` and its dependencies: either
+using :ref:`sec_installation_conda` or :ref:`sec_installation_pip`.
+We recommend conda for most users (particularly those using OSX or Windows),
+although pip can be more convenient in certain cases.
+
+.. _sec_installation_requirements:
+
+************
+Requirements
+************
+
+Library requirements for stdpopsim should be installed automatically when using
+either conda or pip.
+
+Stdpopsim requires Python 3.5 or later.
+
+
+.. _sec_installation_conda:
+
+*****
+Conda
+*****
+
+.. todo:: The conda package for stdpopsim is currently under development and will
+    be available shortly. Please use pip for now.
+
+
+.. _sec_installation_pip:
+
+***
+Pip
+***
+
+Installing using pip is usually as simple as::
+
+    $ python -m pip install stdpopsim --user
+
+This will install ``stdpopsim`` into your local user Python packages
+(on some systems you will need to use ``python3`` rather than
+``python``). Please see the Python `package installation
+<https://packaging.python.org/tutorials/installing-packages/>`_
+tutorial for more details on the various installation options. In particular,
+we recommend using a `virtual environment
+<https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments>`_
+to improve reproducibility.
+
+It may also be necessary to update your PATH to run the command
+line interface. See `here
+<https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site>`_
+for details on what this means and how to do it.
+
+We use `msprime <https://msprime.readthedocs.io/>`_ as the
+default simulation engine, which has some system level dependencies
+and requires a functioning compiler. Please see the msprime
+`installation documentation
+<https://msprime.readthedocs.io/en/stable/installation.html>`_ for
+instructions if you encounter errors during installation.
+
+.. _sec_installation_running_cli:
+
+***************
+Running the CLI
+***************
+
+After installation is complete it should be possible to run the
+:ref:`command line interface <sec_cli_args>`. This can be done in one
+of two ways:
+
+1. The most reliable way is to use ::
+
+       $ python -m stdpopsim
+
+   Once the ``python`` executable is the same one as was used when installing
+   ``conda`` or ``pip``, this is guaranteed to work.
+
+2. It is also possible to run ``stdpopsim`` like a regular Unix program
+   using::
+
+    $ stdpopsim
+
+   However, this requires that your `PATH <https://en.wikipedia.org/wiki/PATH_(variable)>`_
+   environment variable contains the directory where conda or pip installed the
+   executable. Please see the specific documentation on these methods above for
+   details on how to do this.
 
-.. todo:: Add installation docs. Should be as simple as ``pip install stdpopsim``.
 

docs/tutorial.rst

@@ -70,7 +70,7 @@ This gives all of the possible demographic models we could simulate. We choose
 the two population out-of-Africa :ref:`model <sec_catalog_homsap_models_outofafrica_2t12>`
 from `Tennesen et al. (2012) <https://doi.org/10.1126/science.1219240>`_ .
 By looking at the model help we
-find that the name for this model is ``ooa_2`` and that we can specify it using
+find that the name for this model is ``OutOfAfrica_2T12`` and that we can specify it using
 the ``--model`` option. We choose to draw two samples from the African
 population and three samples from the European population. To increase
 simulation speed we can also chose to simulate a sequence a fraction of the
@@ -81,7 +81,7 @@ uniform recombination map. The command now looks like this:
 
 .. code-block:: console
 
-    $ stdpopsim HomSap -c chr22 -l 0.05 -o foo.ts --model ooa_2 2 3
+    $ stdpopsim HomSap -c chr22 -l 0.05 -o foo.ts --model OutOfAfrica_2T12 2 3
 
 Note that there are now two numbers after the model option. This is because the
 model simulates two populations so we have to specify a number of samples to
@@ -98,14 +98,14 @@ the ``-l`` option. (NOTE: this may a minute or so to run).
 
 .. code-block:: console
 
-    $ stdpopsim HomSap -g HapmapII_GRCh37 -c chr22 -o foo.ts --model ooa_2 2 3
+    $ stdpopsim HomSap -g HapMapII_GRCh37 -c chr22 -o foo.ts --model OutOfAfrica_2T12 2 3
 
 For reproducibility we can also choose set seed for the simulator using the
 ``-s`` flag.
 
 .. code-block:: console
 
-    $ stdpopsim HomSap -s 1046 -g HapmapII_GRCh37 -c chr22 -o foo.ts --model ooa_2 2 3
+    $ stdpopsim HomSap -s 1046 -g HapMapII_GRCh37 -c chr22 -o foo.ts --model OutOfAfrica_2T12 2 3
 
 Lastly, the CLI also outputs the relevant citations for both the simulator used
 and the resources used for simulation scenario.
@@ -262,8 +262,8 @@ This prints detailed information about all of the available models to
 the terminal.
 In this tutorial, we will use the model of African-American admixture from
 `2011 Browning et al <http://dx.doi.org/10.1371/journal.pgen.1007385>`_.
-From the help output (or the :ref:`Catalog <sec_catalog>`),
-we can see that this model has id ``america``,
+From the help output (or the :ref:`Catalog <sec_catalog_homsap_models_americanadmixture_4b11>`),
+we can see that this model has id ``AmericanAdmixture_4B11``,
 and allows samples to be drawn from 4 contemporary populations representing African,
 European, Asian and African-American groups.
 
@@ -272,7 +272,7 @@ are available:
 
 .. command-output:: stdpopsim HomSap --help-genetic-maps
 
-Let's go with ``HapmapII_GRCh37``.
+Let's go with ``HapMapII_GRCh37``.
 The next command simulates 4 samples of chromosome 1 from each of the four
 populations, and saves the output to a file called ``afr-america-chr1.trees``.
 For the purposes of this tutorial, we'll also specify a random seed using the
@@ -281,8 +281,8 @@ For the purposes of this tutorial, we'll also specify a random seed using the
 
 .. code-block:: console
 
-    $ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapmapII_GRCh37\
-    --model america 4 4 4 4
+    $ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh37\
+    --model AmericanAdmixture_4B11 4 4 4 4
 
 --------------------------
 2. Calculating divergences

setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name='stdpopsim',
-    description='Standard simulation models for msprime',
+    description='A library of population genetic simulation models',
     long_description=long_description,
     author='PopSim Consortium',
     # TODO probably should have a different email address?
@@ -33,10 +33,10 @@
     },
     # NOTE: make sure this is the 'attrs' package, not 'attr'!
     install_requires=["msprime", "attrs", "appdirs", "humanize"],
-    url='https://github.com/popgensims/stdpopsim',
+    url='https://github.com/popsim-consortium/stdpopsim',
     project_urls={
-        'Bug Reports': 'https://github.com/popgensims/stdpopsim/issues',
-        'Source': 'https://github.com/tsckit-dev/stdpopsim',
+        'Bug Reports': 'https://github.com/popsim-consortium/stdpopsim/issues',
+        'Source': 'https://github.com/popsim-consortium/stdpopsim',
     },
     license="GNU GPLv3+",
     platforms=["POSIX", "MacOS X", "Windows"],