cleaned it up a bit

Author: ChrisBarker-NOAA

Sources/source/conf.py

@@ -34,10 +34,10 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.pngmath',
+    'sphinx.ext.imgmath',
     'sphinx.ext.ifconfig',
     'IPython.sphinxext.ipython_console_highlighting',
-    'IPython.sphinxext.ipython_directive',
+    # 'IPython.sphinxext.ipython_directive',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

Sources/source/interfacing_with_c/c_python.rst

@@ -1,55 +1,57 @@
+########################
 Interfacing C and Python
-################################
+########################
 
-Sorry, not much here
+Sorry, not much here yet.
 
 NOTE: this is all about the CPython interpreter -- not PyPy, IronPython, JPython, etc.
 
 Documentation:
-================
+==============
 
 Core docs for the C API:
 
 
 
 
 Interfacing methods:
-======================
+====================
 
 There a bunch of ways to interface C and Python:
 
 Hand write against the C API:
-------------------------------
+-----------------------------
 
-The python interpeter exposes a full API to all teh pyton objects, etc. You can essentially do anything, but it's a lot of hand-work.
+The python interpeter exposes a full API to all the python objects, etc. You can essentially do anything, but it's a lot of hand-work.
 
 And reference counting is really hard to get right!
 
-http://docs.python.org/2/c-api/
+http://docs.python.org/3/c-api/
 
 Cython:
-------------------
+-------
 
 Cython can be described as a "python-like language for writing python extensions"
 
-It can be used essentially to speed up Python, but also to Call Python from C
+It can be used essentially to speed up Python, but also to call Python from C.
 
 (derived from Pyrex)
 
 XDress
-........
+......
 
 ctypes
---------
+------
 
 
 SWIG, SIP, ETC.
-----------------
+---------------
 
 Auto wrapper generators.
 
 
 EXAMPLE:
-============
+========
+
+Same as the one for fortran: a automatic gain control filter.
 
-Same as the one for fortran: a automatic gain control filter.

Sources/source/interfacing_with_c/fortran_python.rst

@@ -1,8 +1,8 @@
 Interfacing Fortran and Python
-################################
+##############################
 
 Documentation:
-================
+==============
 
 A nice reference for Python for Fortran programmers:
 
@@ -16,7 +16,7 @@ http://fortran90.org/src/best-practices.html
 http://fortran90.org/src/best-practices.html#interfacing-with-python
 
 Interfacing methods:
-======================
+====================
 
 There a a handful of ways to interface Fortran and Python:
 
@@ -75,7 +75,7 @@ The problem at hand is an automatic gain control function function, expressed in
       end
 
 f2py:
--------
+-----
 
 f2py is a command line utility that comes with numpy. You can build a default simple wrapper with the f2py command::
 
@@ -108,7 +108,7 @@ So it can be called like so::
 where `signal` and `filtered` are 1-d arrays of float32 values, both of the same length.
 
 Giving f2py extra information:
-...............................
+..............................
 
 f2py can build an interface to a fortran subroutine, but it can't do it all that well without some extra information. For instnce, note from the docstring that the argument `ampagc` is listed as an input argument, when it is really intended to be used for output.
 

Sources/source/where_to_put_your_code.rst

@@ -2,6 +2,8 @@
 Where to put your custom code?
 ******************************
 
+(You can find this page at: http://bit.ly/JustPackage)
+
 A suggestion for how to manage your personal library of python functions you might use for scripting, data analysis, etc.
 
 TL; DR
@@ -14,13 +16,19 @@ Make a "package" out of it so you can manage it in one place, and use it in othe
 Introduction
 ------------
 
-Many folks find they have a collection of little scripts and utilities that they want to be able to use and re-use for various projects. It is really NOT a good idea to simply copy and paste these around for use with each project -- you will regret that!
+Many scientists and engineers that do a little coding find they have a collection of little scripts and utilities that they want to be able to use and re-use for various projects. It is really NOT a good idea to simply copy and paste these around for use with each project -- you will regret that!
 
 It is also not a good idea to use the ``PYTHONPATH`` environment variable to set up a directory in which to dump stuff. (Google a bit if you want to know why).
 
-The best way to do this with Python is to use the python package mechanism.
+The best way to do this with Python is to use the Python package mechanism.
+
+A Python "package" is a collection of modules and scripts -- we usually think of these as something carefully developed for a particular purpose and distributed to a wide audience for re-use -- the packages you can install with pip.
+
+Indeed that is the case, but the "collection of modules and scripts" part can be used for your own code that no one else is ever going to touch, and the overhead is small if you use it only this way.
+
+The challenge is that most of the documentation about python packaging is focused on creating a package of a library that you want to distribute to the community. In that case, it's very important to have full and proper meta data, tests, documentation, etc. As a result, the packaging documentation makes the whole process seem complicated and cumbersome.
 
-A Python "package" is a collection of modules and scripts -- we usually think of these as something carefully developed for particular purpose and distributed to a wide audience for re-use -- the packages you can install with pip. Indeed that is the case, but the "collection of modules and scripts" part can be used for your own code that no one else is ever going to touch, and the overhead is small if you use it only this way.
+But making a simple package for your own use can be very simple, and very useful.
 
 Step by step:
 -------------
@@ -33,18 +41,18 @@ Step by step:
 
 4) In the outer dir, put in a file (we'll fill it in later) called ``setup.py``.
 
-So you shoudl have::
+So you should have::
 
   my_code
       my_code
           __init__.py
       setup.py
 
-The inner my_code dir is now a python "package" -- any directory with a __init__.py file is a package. But how to use it?
+The inner my_code dir is now a python "package" -- any directory with a ``__init__.py`` file is a package. But how to use it?
 
-The setup.py file is where you specify for python how this package is setup. You can do a lot in there, and if you ever want to share your code with anyone else, you should follow:
+The ``setup.py`` file is where you specify for python how this package is setup. You can do a lot in there, and if you ever want to share your code with anyone else, you should follow:
 
-https://packaging.python.org/tutorials/distributing-packages/.
+https://packaging.python.org/tutorials/distributing-packages/
 
 But for now, we are going to make it as *simple* as possible::
 
@@ -56,6 +64,7 @@ But for now, we are going to make it as *simple* as possible::
 
 That's it -- really! There is a lot you can do here to support multiple packages, scripts, etc, but this is enough to get you started.
 
+
 Putting in your code
 --------------------
 
@@ -80,15 +89,19 @@ Create a file for your code, and put it in the inner my_code dir:
 
 OK -- now you have a (useless) package with some code in it - how to use it?
 
-To use this package, you need to "install" it into the python environment that you want to use. Some of us have a single python install -- maybe Anaconda's root environment, or the python.org python installer, or.... Some of us use virtualenv or conda environments. In any case, get yourself into that environment with a command line in the outer my_code dir, and type::
+To use this package, you need to "install" it into the python environment that you want to use. Some of us have a single python install -- maybe Anaconda's root environment, or the python.org python installer, or ...
+
+Some of us use virtualenv, or pipienv, or conda environments. In any case, get yourself into that environment at a command line and put yourself (``cd`` in Terminal, DOS box, etc...)  in the outer my_code dir (where the setup.py  is), and type::
+
+    pip install -e .
 
-    python setup.py develop
+``pip install`` installs a package. ``-e`` means "do an editable install", and the dot (``.``) tells pip to install the package in the current directory. ``pip`` will look for a ``setup.py`` file in the current working dir. An editable install is like install, but instead of copying the code into the python environment, it adds it to the Python search path (only that particular environment's Python) so you can import it, but it will always be importing the current version of the files if you change things.
 
-"develop" is like install, but instead of copying the code into the python environment, it adds it to the python search path (only that particular python instances search path!) so you can import it, but it will always be importing the current version of the files if you change things.
+This means you can be actively maintaining your shared code, and other projects that use it will always get the latest version.
 
-Now you can fire up python (or ipython, or a Jupyter notebook, or write code in a script, or...) and do::
+Now you can fire up Python (or iPython, or a Jupyter notebook, or write code in a script, or...) and do:
 
-    from my_code import some_code
+.. code-block:: ipython
 
     In [2]: from my_code import some_code
 
@@ -108,12 +121,13 @@ If you have only a little bit of code, you can do all this with a single module,
 
 If you have more than a few modules, it would probably make sense to keep them in separate packages, organized by functionality.
 
-This is only the very simplest way to do it what you really SHOULD do is be more formal about the process:
+This is only the very simplest way to do it. What you really SHOULD do is be more formal about the process:
   - Do some versioning of the package
   - Keep it in source code version control system (like git, etc)
+  - add tests of your code...
 
 and others...
 
-Look up "Software Carpentry" for many more ideas how better to manage your software for Science.
+Look up "Software Carpentry" for many more ideas about how better to manage your Software for Science.