Merge pull request Pyomo#3208 from mrmundt/document-cython

Update installation documentation to include Cython instructions

Author: mrmundt

Diff for: doc/OnlineDocs/installation.rst

@@ -12,7 +12,7 @@ version, Pyomo will remove testing for that Python version.
 Using CONDA
 ~~~~~~~~~~~
 
-We recommend installation with *conda*, which is included with the
+We recommend installation with ``conda``, which is included with the
 Anaconda distribution of Python. You can install Pyomo in your system
 Python installation by executing the following in a shell:
 
@@ -21,7 +21,7 @@ Python installation by executing the following in a shell:
    conda install -c conda-forge pyomo
 
 Optimization solvers are not installed with Pyomo, but some open source
-optimization solvers can be installed with conda as well:
+optimization solvers can be installed with ``conda`` as well:
 
 ::
 
@@ -31,7 +31,7 @@ optimization solvers can be installed with conda as well:
 Using PIP
 ~~~~~~~~~
 
-The standard utility for installing Python packages is *pip*.  You
+The standard utility for installing Python packages is ``pip``.  You
 can install Pyomo in your system Python installation by executing
 the following in a shell:
 
@@ -43,14 +43,14 @@ the following in a shell:
 Conditional Dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Extensions to Pyomo, and many of the contributions in `pyomo.contrib`,
+Extensions to Pyomo, and many of the contributions in ``pyomo.contrib``,
 often have conditional dependencies on a variety of third-party Python
 packages including but not limited to: matplotlib, networkx, numpy,
 openpyxl, pandas, pint, pymysql, pyodbc, pyro4, scipy, sympy, and
 xlrd. 
 
 A full list of conditional dependencies can be found in Pyomo's
-`setup.py` and displayed using:
+``setup.py`` and displayed using:
 
 ::
 
@@ -72,3 +72,28 @@ with the standard Anaconda installation.
 You can check which Python packages you have installed using the command
 ``conda list`` or ``pip list``. Additional Python packages may be
 installed as needed.
+
+
+Installation with Cython
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can opt to install Pyomo with
+`cython <https://cython.readthedocs.io/en/latest/src/tutorial/cython_tutorial.html>`_
+initialized.
+
+.. note::
+   This can only be done via ``pip`` or from source.
+
+Via ``pip``:
+
+::
+
+   pip install pyomo --global-option="--with-cython"
+
+From source (recommended for advanced users only):
+
+::
+
+   git clone https://github.com/Pyomo/pyomo.git
+   cd pyomo
+   python setup.py install --with-cython