Merge pull request #3 from lightwave-lab/development

v1.0.3

Author: thomaslima

.readthedocs.yml

@@ -0,0 +1,18 @@
+language: python
+python:
+- '3.6'
+install:
+- pip install -U virtualenv pip
+- python --version
+script:
+- DOCKER=1 make test-unit-all
+- make test-lint-errors
+- if [ "$TRAVIS_BRANCH" = "master" ]; then make test-lint; fi
+deploy:
+  provider: pypi
+  user: thomaslima
+  password:
+    secure: FbL4S5mRqyZeKt1ZHoEyE53kgkaKBdVfztxbEYfTfhNgaQg94BUmd/x5IWBCORIqF7s0ywkkP+kK9LRFrA5Ymu50hbwAAODnIEEax5xcYE825c0cagXQdKsMG/MGVDGOxlcO+1DQN6zZnfcOVX6fGqm9pEBN2s4Ej0YfabrqdeebvVb53pyCXS43veGXQ8jyMr48eHdig3rksnWb5uKBUrfW1g8wxdCntym4vJRxrdA4zZIuG1osfkxd1sX5rUXcnPNc+6czXwSFsVoRgrr5RvUFYGDGGjuCQ4UVeRe3/V2pSN543FaG6HWP0xpJYGw2dcsML8ykIOIX1oRf2bO2dD485KJHdmkHpgafiB7fnDqwiw0uah/PJkdLtd1tWk4/y0txsEQJhK1qZdHRf5wSfGAIK2XvQPuQXL/MZ8BUIojYd0Ay+JwnkvB57bubGotmvwjWmdDbMMrSWI1B+6UgjHjPN7rQU8qMgV10/IyH51fCvd+2uMQX6D3I7CXS5o8ELy9OsboSxzPxNOxitmq/oGoMKAlg3nhqvYCNZXoxHip+aamqUtccYKaYZuv5ma+WIhAAJt6h5IJ1J3d5wBz6dILXzUYhw3IoXzrGdEG5TSdjrDdmmgxjKrCybxGkbTTLFS69pKa6XGwB9D0qhxKEdJmaFrGojm0zDFOsQwcHse8=
+  on:
+    tags: true
+    branch: master

.travis.yml

@@ -1 +1,6 @@
 # CHANGELOG
+
+1.0.3:
+    - added documentation for lightlab command line tool
+    - added a driver for HP 8157A Optical Variable attenuator
+    - added travis-ci integration

CHANGELOG

@@ -69,6 +69,7 @@ test-nb: testbuild
 	( \
 		source venv/bin/activate; \
 		py.test $(TESTARGS) $(TESTARGSNB) notebooks/Tests; \
+		rsync -rau notebooks/Tests/*.ipynb docs/ipynbs/Tests
 	)
 
 test-unit-all: testbuild
@@ -143,7 +144,6 @@ venvinfo/docreqs~: $(REINSTALL_DEPS) notebooks/Tests doc-requirements.txt
 	@touch venvinfo/docreqs~
 
 docs: docbuild
-	rsync -rau notebooks/Tests/*.ipynb docs/ipynbs/Tests
 	source venv/bin/activate; $(MAKE) -C docs $(DOCTYPE_DEFAULT)
 
 docs-ci: docbuild

Makefile

@@ -0,0 +1,95 @@
+Contributing to ``lightlab``
+============================
+We follow this `Git branching workflow <http://nvie.com/posts/a-successful-git-branching-model/>`_. Feature branches should base off of development; when they are done, they must pass tests and test-nb's; finally they are merged to development.
+
+Testing ``lightlab``
+--------------------
+First off, your change should not break existing code. You can run automated tests like this::
+
+    make test-unit
+    make test-nb
+
+The test-nb target runs the **notebooks** in notebooks/Tests. This is a cool feature because it allows you to go in with jupyter and see what's happening if it fails. We recommend using the `nbval <https://github.com/computationalmodelling/nbval>`_ approach. It checks for no-exceptions, not accuracy of results. If you want to check for accuracy of results, do something like::
+
+    x = 1 + 1
+    assert x == 2
+
+in the cell.
+
+**Make tests for your features!** It helps a lot. Again, **Never put hardware accessing methods in a unittest**.
+
+To run just one test, use a command like::
+
+    $ source venv/bin/activate
+    $ py.test --nbval-lax notebooks/Tests/TestBook.ipynb
+
+Documenting
+-----------
+Documenting as you go is helpful for other developers and code reviewers.  So useful that we made a whole :doc:`tutorial <docYourCode>` on it. We use auto-API so that docstrings in code make it into the official documentation.
+
+For non-hardware features, a good strategy is to use tests that are both functional and documentation by example. In cases where visualization is helpful, use notebook-based, which can be linked from this documentation or in-library docstrings :ref:`like this </ipynbs/Tests/TestPeakAssistant.ipynb>`. Otherwise, you can make `pytest <https://docs.pytest.org/en/latest/>`_ unittests in the tests directory, which can be linked like this: :py:mod:`~tests.test_virtualization`.
+
+For new hardware drivers, as a general rule, document its basic behavior in ``lightlab/notebooks/BasicHardwareTests``. Make sure to save with outputs. Finally, link it in the docstring like this::
+
+    class Tektronix_DPO4034_Oscope(VISAInstrumentDriver, TekScopeAbstract):
+    ''' Slow DPO scope. See abstract driver for description
+
+        `Manual <http://websrv.mece.ualberta.ca/electrowiki/images/8/8b/MSO4054_Programmer_Manual.pdf>`__
+
+        Usage: :any:`/ipynbs/Hardware/Oscilloscope.ipynb`
+
+    '''
+    instrument_category = Oscilloscope
+    ...
+
+Linting
+-------
+As of now, we don't require strict `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ compliance, but we might in the future. However, we try to follow as many of their guidelines as possible:
+
+.. figure:: images/sublimelinter_example_bad.png
+    :alt: bad pep8 example
+
+    Example of valid python code that violates some of the PEP8 guidelines.
+
+.. figure:: images/sublimelinter_example_good.png
+    :alt: good pep8 example
+
+    Fixing the PEP8 violations of the previous figure.
+
+Sometimes the linter is wrong. You can tell it to ignore lines by adding comment flags like the following example:
+
+.. code:: python
+
+    x = [x for x in sketchy_iterable]  # pylint: disable=not-an-iterable
+    from badPractice import *  # noqa
+
+``# noqa`` is going to ignore pyflakes linting, whereas ``# pylint`` configures `pylint` behavior.
+
+If you use Sublime editor
+-------------------------
+Everyone has their favorite editor. We like `Sublime Text <https://www.sublimetext.com>`_. If you use Sublime, `here <https://github.com/SublimeLinter/SublimeLinter-flake8>`_ is a good linter. It visually shows what is going on while you code, saving lots of headaches
+
+Sublime also helps you organize your files, autocomplete, and manage whitespace. This is :doc:`sublime-lightlab`. Put it in the ``lightlab/`` directory and call it something like ``sublime-lightlab.sublime-project``.
+
+By the way, you can make a command-line Sublime by doing this in Terminal (for MacOS)::
+
+    ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl
+
+Adding a new package
+--------------------
+Two ways to do this. The preferred method is to add it to the package requirements in ``setup.py``. The other way is in the venv. In that case, make sure you freeze the new package to the requirements file::
+
+    $ source venv/bin/activate
+    $ pip install <package>
+    $ make pip-freeze
+    $ git commit -m "added package <package> to venv"
+
+.. warning::
+
+    If your code imports an external package, the sphinx documentation will try to load it and fail. The solution is to mock it. Lets say your source file wants to import::
+
+        import scipy.optimize as opt
+
+    For this to pass and build the docs, you have to go into the ``docs/sphinx/conf.py`` file. Then add that package to the list of mocks like so::
+
+        MOCK_MODULES = [<other stuff>, 'scipy.optimize']

docs/_static/developers/contributing.rst

@@ -240,101 +240,6 @@ It's not really necessary in this example where there is just a notebook. If you
 
 Unittests are designed to be run in an automated way in a repeatable setting. Firstly, the real world is not repeatable. Secondly, an automated run could do something unintended and damaging to the currently connected devices.
 
-Contributing to ``lightlab``
-------------------------------
-We follow this `Git branching workflow <http://nvie.com/posts/a-successful-git-branching-model/>`_. Feature branches should base off of development; when they are done, they must pass tests and test-nb's; finally they are merged to development.
-
-Testing ``lightlab``
-^^^^^^^^^^^^^^^^^^^^
-First off, your change should not break existing code. You can run automated tests like this::
-
-    make test-unit
-    make test-nb
-
-The test-nb target runs the **notebooks** in notebooks/Tests. This is a cool feature because it allows you to go in with jupyter and see what's happening if it fails. We recommend using the `nbval <https://github.com/computationalmodelling/nbval>`_ approach. It checks for no-exceptions, not accuracy of results. If you want to check for accuracy of results, do something like::
-
-    x = 1 + 1
-    assert x == 2
-
-in the cell.
-
-**Make tests for your features!** It helps a lot. Again, **Never put hardware accessing methods in a unittest**.
-
-To run just one test, use a command like::
-
-    $ source venv/bin/activate
-    $ py.test --nbval-lax notebooks/Tests/TestBook.ipynb
-
-Documenting
-^^^^^^^^^^^^^^
-Documenting as you go is helpful for other developers and code reviewers.  So useful that we made a whole :doc:`tutorial <docYourCode>` on it. We use auto-API so that docstrings in code make it into the official documentation.
-
-For non-hardware features, a good strategy is to use tests that are both functional and documentation by example. In cases where visualization is helpful, use notebook-based, which can be linked from this documentation or in-library docstrings :ref:`like this </ipynbs/Tests/TestPeakAssistant.ipynb>`. Otherwise, you can make `pytest <https://docs.pytest.org/en/latest/>`_ unittests in the tests directory, which can be linked like this: :py:mod:`~tests.test_virtualization`.
-
-For new hardware drivers, as a general rule, document its basic behavior in ``lightlab/notebooks/BasicHardwareTests``. Make sure to save with outputs. Finally, link it in the docstring like this::
-
-    class Tektronix_DPO4034_Oscope(VISAInstrumentDriver, TekScopeAbstract):
-    ''' Slow DPO scope. See abstract driver for description
-
-        `Manual <http://websrv.mece.ualberta.ca/electrowiki/images/8/8b/MSO4054_Programmer_Manual.pdf>`__
-
-        Usage: :any:`/ipynbs/Hardware/Oscilloscope.ipynb`
-
-    '''
-    instrument_category = Oscilloscope
-    ...
-
-Linting
-^^^^^^^
-As of now, we don't require strict `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ compliance, but we might in the future. However, we try to follow as many of their guidelines as possible:
-
-.. figure:: images/sublimelinter_example_bad.png
-    :alt: bad pep8 example
-
-    Example of valid python code that violates some of the PEP8 guidelines.
-
-.. figure:: images/sublimelinter_example_good.png
-    :alt: good pep8 example
-
-    Fixing the PEP8 violations of the previous figure.
-
-Sometimes the linter is wrong. You can tell it to ignore lines by adding comment flags like the following example:
-
-.. code:: python
-
-    x = [x for x in sketchy_iterable]  # pylint: disable=not-an-iterable
-    from badPractice import *  # noqa
-
-``# noqa`` is going to ignore pyflakes linting, whereas ``# pylint`` configures `pylint` behavior.
-
-If you use Sublime editor
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Everyone has their favorite editor. We like `Sublime Text <https://www.sublimetext.com>`_. If you use Sublime, `here <https://github.com/SublimeLinter/SublimeLinter-flake8>`_ is a good linter. It visually shows what is going on while you code, saving lots of headaches
-
-Sublime also helps you organize your files, autocomplete, and manage whitespace. This is :doc:`sublime-lightlab`. Put it in the ``lightlab/`` directory and call it something like ``sublime-lightlab.sublime-project``.
-
-By the way, you can make a command-line Sublime by doing this in Terminal (for MacOS)::
-
-    ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl
-
-Adding a new package
-^^^^^^^^^^^^^^^^^^^^^
-Two ways to do this. The preferred method is to add it to the package requirements in ``setup.py``. The other way is in the venv. In that case, make sure you freeze the new package to the requirements file::
-
-    $ source venv/bin/activate
-    $ pip install <package>
-    $ make pip-freeze
-    $ git commit -m "added package <package> to venv"
-
-.. warning::
-
-    If your code imports an external package, the sphinx documentation will try to load it and fail. The solution is to mock it. Lets say your source file wants to import::
-
-        import scipy.optimize as opt
-
-    For this to pass and build the docs, you have to go into the ``docs/sphinx/conf.py`` file. Then add that package to the list of mocks like so::
-
-        MOCK_MODULES = [<other stuff>, 'scipy.optimize']
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/_static/developers/developer.rst

@@ -1,10 +1,13 @@
-Developer guide
+Making your changes to lightlab
 ================================================
 
+The following texts should help you in the process or making changes to lightlab itself. If you are looking for a way to include your own instrument driver, you will find instructions in :ref:`creating_drivers`. After you are done, please consider submitting a pull request via github! :) We the community will be glad to provide feedback.
+
 .. toctree::
    :maxdepth: 2
 
    developer
+   contributing
    docYourCode
    labState
 

docs/_static/developers/index.rst

@@ -1,5 +1,7 @@
 # An engineer’s guide to modern lab control
 
+Author: *Thomas Ferreira de Lima* ([email protected])
+
 ## Introduction
 
 Over the years, software engineering has evolved into a very prominent field that penetrates all industrial sectors. Its core principles and philosophy was to make life easier for consumers to achieve their goals. That was when Apple and Microsoft were created. Then, as the field evolved, it has become important to make software engineering as inclusive as possible to new “developers”, and to make collaboration as seamless as possible. This is the age of the apps. Now, software programming is becoming considered as fundamental as math and science, and are starting to enter school curricula.
@@ -57,7 +59,7 @@ git commit -m “finished simulation”
 git push
 ```
 
-![How git push works.](https://wac-cdn.atlassian.com/dam/jcr:f148974e-7d4d-4c0e-bd31-8ac5467d1e6a/04.svg?cdnVersion=ie)
+![How git push works. From Atlassian.](images/atlassian_push.png)
 
 The other main property of Git is that it can automatically “merge” a number of edits together in one step. Its algorithm is very powerful, works flawlessly when it can, and falls back to human intervention in case of “conflicts”. When two collaborators create local commits, their history tree forks into two parallel versions that need to be conciliated. If one pushes first, the other’s push will fail and abort, because its local repository does not agree with the most recent state of the remote repository. So the proper procedure is to sync the local with the remote by “pulling” changes from remote:
 

docs/_static/gettingStarted/engineersGuide.md

@@ -1,15 +1,12 @@
 .. _getting-started:
 
-Getting Started
+Getting Started to Python, Jupyter, git
 ================================================
 
+.. todo::
+    Include more tutorial pages and useful links for intriductory python.
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    engineersGuide
-   user
-   sysadmin
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`