Merge pull request #31 from EdinburghGenomics/mwham_develop

Refactor/doc improvements

README.md

@@ -7,9 +7,9 @@
 [![Coverage Status](https://coveralls.io/repos/github/EdinburghGenomics/pyclarity-lims/badge.svg)](https://coveralls.io/github/EdinburghGenomics/pyclarity-lims)
 
 
-Pyclarity-lims is a fork of [genologics](https://github.com/SciLifeLab/genologics) that we extended and modified.
-Most of the initial logic still applies and genologics module still exist in pyclarity-lims for backward compatibility.
-However there are a few backward incompatible changes that had to be made.
+Pyclarity-lims is a fork of [genologics](https://github.com/SciLifeLab/genologics) that we have extended and modified.
+Most of the initial logic still applies and the `genologics` module still exists as an alias for backward compatibility.
+However there are a few backward incompatible changes that have had to be made.
 
 ## Documentation
 

docs/Getting_started.rst

@@ -2,20 +2,20 @@
 Getting started
 ===============
 
-pyclarity-lims is a module that will help you access you `Basespace-clarity <https://www.genologics.com/clarity-lims/>`_ REST API by parsing the xml the API returns and provide python object.
+pyclarity-lims is a module that will help you access your `Basespace-clarity <https://www.genologics.com/clarity-lims/>`_ REST API by parsing the xml the API returns into Python objects.
 
 Lims connection
 ---------------
 
-To create a lims connection you'll need to create a :py:class:`Lims <pyclarity_lims.lims.Lims>` object.
+To create a Lims connection you'll need to create a :py:class:`Lims <pyclarity_lims.lims.Lims>` object.
 
 .. code::
 
         from pyclarity_lims.lims import Lims
 
         l = Lims('https://claritylims.example.com', 'username' , 'Pa55w0rd')
 
-The :py:class:`Lims <pyclarity_lims.lims.Lims>` instance is the main object that will interact with REST API and manage all communications.
+The :py:class:`Lims <pyclarity_lims.lims.Lims>` instance is the main object that will interact with the REST API and manage all communications.
 There are two way of accessing information stored in the LIMS:
 
 Searching the Lims
@@ -26,15 +26,15 @@ The most common way of accessing data from the LIMS is to first perform searches
 
         samples = l.get_samples(projectname='project1')
 
-This will return the list of :py:class:`Sample <pyclarity_lims.entities.Sample>` objects that belong to project1.
+This will return a list of all :py:class:`Sample <pyclarity_lims.entities.Sample>` objects that belong to project1.
 
 The functions from pyclarity_lims closely match the API search function from Basespace-clarity REST API. For example
 :py:func:`get_samples <pyclarity_lims.lims.Lims.get_samples>` has similar parameters as the
 `samples end point <https://www.genologics.com/files/permanent/API/latest/rest.version.samples.html>`_ from Basespace-clarity
 
 Retrieving object with their id
 -------------------------------
-In some case you will know the id or uri of the instance you want to retrieve. In this case you can create the object directly.
+In some cases you will know the id or uri of the instance you want to retrieve. In this case you can create the object directly.
 
 Note that you will still need the :py:class:`Lims <pyclarity_lims.lims.Lims>` instance as an argument.
 
@@ -51,8 +51,8 @@ Lazy loading and caching
 All entities such as :py:class:`Sample <pyclarity_lims.entities.Sample>`,
 :py:class:`Artifact <pyclarity_lims.entities.Artifact>` or
 :py:class:`Step <pyclarity_lims.entities.Step>` are loaded lazily which mean that no query will be sent to the REST API
-until an attribute of method of the object is accessed.
-In the code above
+until an attribute of the object is accessed or a method is run.
+In the code above:
 
 .. code::
 
@@ -62,12 +62,12 @@ In the code above
         print(sample.name)
         # accessing the name of the sample triggers the query
 
-To avoid sending to many queries all Entities that have been retrieved are also cached which means that once the Entity is retrieved it won't be queried unless forced.
-This make pyclarity_lims more efficient but also not very well suited for long running process during which the state of the LIMS is likely to change.
+To avoid sending too many queries, all Entities that have been retrieved are also cached which means that once the Entity is retrieved it won't be queried again unless forced.
+This makes pyclarity_lims more efficient but also not very well suited for long running process during which the state of the LIMS is likely to change.
 You can bypass the cache as shown in :ref:`up-to-date-program-status`.
 
 Looking beyond
 --------------
 You can look at some :doc:`PracticalExamples`
-There are many other searches method available in the :py:class:`Lims <pyclarity_lims.lims.Lims>` and
+There are many other search methods available in the :py:class:`Lims <pyclarity_lims.lims.Lims>` and
 you can also look at all the classes defined in :doc:`entities`

docs/Installation.rst

@@ -1,6 +1,6 @@
 
 Installation
-=============
+============
 
 .. code:: bash
 

docs/PracticalExamples.rst

@@ -4,8 +4,8 @@ Practical Examples
 Change value of a UDF of all artifacts of a Step in progress
 ------------------------------------------------------------
 
-The goal of this example is to show how you could change the value of a UDF named udfname in all input artifacts.
-This example assume you have a :py:class:`Lims <pyclarity_lims.lims.Lims>` and a process id.
+The goal of this example is to show how you can change the value of a UDF named udfname in all input artifacts.
+This example assumes you have a :py:class:`Lims <pyclarity_lims.lims.Lims>` and a process id.
 
 .. code::
 
@@ -18,12 +18,12 @@ This example assume you have a :py:class:`Lims <pyclarity_lims.lims.Lims>` and a
             # upload the artifact back to the Lims
             artifact.put()
 
-In some cases we want to optimise the number of query sent to the LIMS and make use of the batched query the API offers.
+In some cases we want to optimise the number of queries sent to the LIMS and make use of the batched query the API offers.
 
 .. code::
 
         p = Process(l, id=process_id)
-        # This time we create all the Artifacts entities and use the batch query to retrieve the content
+        # This time we create all the Artifact entities and use the batch query to retrieve the content
         # then iterate over them
         for artifact in p.all_inputs(resolve=True):
             artifact.udf['udfname'] = 'udfvalue'
@@ -32,7 +32,7 @@ In some cases we want to optimise the number of query sent to the LIMS and make
 
 .. note::
 
-        the batch queries are ususally faster than the equivalent multiple individual queries.
+        A batch query is usually faster than the equivalent number of individual queries.
         However the gain seems very variable and is not as high as one might expect.
 
 Find all the samples that went through a Step with a specific udf value
@@ -54,7 +54,7 @@ Make sure to have the up-to-date program status
 -----------------------------------------------
 
 Because all the entities are cached, sometime the Entities get out of date especially
-when the data in the LIMS  is changing rapidly: like the status of a running program.
+when the data in the LIMS is changing rapidly, like the status of a running program.
 
 .. code::
 
@@ -71,7 +71,7 @@ but can be used explicitly with the force option to bypass the cache and retriev
 Create sample with a Specific udfs
 ----------------------------------
 
-So far we always retrieve entities from the LIMS and in some case modified them before uploading them back.
+So far we have only retrieved entities from the LIMS and in some case modified them before uploading them back.
 We can also create some of these entities and upload them to the LIMS.
 Here is how to create a sample with a specific udf.
 
@@ -81,9 +81,9 @@ Here is how to create a sample with a specific udf.
 
 
 Start and complete a new Step from submitted samples
----------------------------------------
+----------------------------------------------------
 
-Creating a step, filling in the placement and the next actions then completing the step
+Creating a step, filling in the placements and the next actions, then completing the step
 can be very convenient when you want to automate the execution of part of your workflow.
 Here is an example with one sample placed into a tube.
 
@@ -109,10 +109,10 @@ Here is an example with one sample placed into a tube.
         output_art = s.details.input_output_maps[0][1]['uri']
 
         # Place the output artifact in the container
-        # Note that the placements is a list of tuple ( A, ( B, C ) )
-        # Where A is output artifact, B the output Container and C the location on this container
+        # Note that the placements is a list of tuples ( A, ( B, C ) ), where A is the output artifact,
+        # B is the output Container and C is the location on this container
         output_placement_list=[(output_art, (c, '1:1'))]
-        # set_placements creates the placement entity and "put" it
+        # set_placements creates the placement entity and "put"s it
         s.set_placements([c], output_placement_list)
 
         # Move from "Record detail" window to the "Next Step"

docs/conf.py

@@ -32,17 +32,14 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.coverage',
-    'sphinx.ext.imgmath',
-    'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
+              'sphinx.ext.imgmath', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
+# You can specify multiple suffixes as a list of strings:
 #
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
@@ -74,13 +71,13 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
+# These patterns also affect html_static_path and html_extra_path
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
+# If true, `todo` and `todoList` produce outputs, else they produce nothing.
 todo_include_todos = False
 
 
@@ -166,4 +163,4 @@
 
 
 # -- Options for side bar ----------------------------------------------------
-html_sidebars = { '**': ['about.html', 'navigation.html', 'relations.html', 'searchbox.html'], }
+html_sidebars = {'**': ['about.html', 'navigation.html', 'relations.html', 'searchbox.html']}

docs/entities.rst

@@ -1,10 +1,8 @@
 
-Entites object
-==========================================
+Entities
+========
 
 .. automodule:: pyclarity_lims.entities
     :members:
     :undoc-members:
     :show-inheritance:
-
-

docs/index.rst

@@ -6,9 +6,9 @@
 Pyclarity-lims
 ==============
 
-Pyclarity-lims is a fork of `genologics <https://github.com/SciLifeLab/genologics>`_ that we extended and modified.
-Most of the initial logic still applies and genologics module still exist in pyclarity-lims for backward compatibility.
-However there are a few backward incompatible changes that had to be made.
+Pyclarity-lims is a fork of `genologics <https://github.com/SciLifeLab/genologics>`_ that we have extended and modified.
+Most of the initial logic still applies and the `genologics` module still exists as an alias for backward compatibility.
+However there are a few backward incompatible changes that have had to be made.
 
 .. image:: https://img.shields.io/pypi/v/pyclarity-lims.svg
     :target: https://pypi.python.org/pypi/pyclarity-lims

docs/lims.rst

@@ -1,6 +1,6 @@
 
 Lims object
-==========================================
+===========
 
 .. autoclass:: pyclarity_lims.lims.Lims
     :members:

genologics/__init__.py

@@ -1,2 +1,2 @@
 from pyclarity_lims import lims
-from pyclarity_lims import entities
+from pyclarity_lims import entities

genologics/entities.py

@@ -1 +1 @@
-from pyclarity_lims.entities import *
+from pyclarity_lims.entities import *

genologics/lims.py

@@ -1 +1 @@
-from pyclarity_lims.lims import *
+from pyclarity_lims.lims import *

integration_tests/integration_tests.py

@@ -1,8 +1,7 @@
-import sys
-from argparse import ArgumentParser
-
 import os
+import sys
 import yaml
+from argparse import ArgumentParser
 from pyclarity_lims.lims import Lims
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
@@ -50,4 +49,4 @@ def main():
 
 
 if __name__ == '__main__':
-    sys.exit(main())
+    sys.exit(main())