update docs to reflect MILP features (#770)

README.rst

@@ -10,74 +10,53 @@ pulp
     :target: https://pypi.org/project/PuLP/
     :alt: PyPI - Downloads
 
-PuLP is an LP modeler written in Python. PuLP can generate MPS or LP files and call GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_ to solve linear problems.
-
-Installation
-================
-
-The easiest way to install pulp is via `PyPi <https://pypi.python.org/pypi/PuLP>`_
-
-If pip is available on your system::
-
-     python -m pip install pulp
-
-Otherwise follow the download instructions on the PyPi page.
-
-
-If you want to install the latest version from github you can run the following::
-
-    python -m pip install -U git+https://github.com/coin-or/pulp
+PuLP is an linear and mixed integer programming modeler written in Python. With PuLP, it is simple to create MILP optimisation problems and solve them with the latest open-source (or proprietary) solvers.  PuLP can generate MPS or LP files and call solvers such as GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_, CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_.
 
+The documentation for PuLP can be `found here <https://coin-or.github.io/pulp/>`_.
 
-On Linux and OSX systems the tests must be run to make the default
-solver executable.
+PuLP is part of the `COIN-OR project <https://www.coin-or.org/>`_. 
 
-::
-
-     sudo pulptest
-
-Examples
+Installation
 ================
 
-See the examples directory for examples.
-
 PuLP requires Python 3.7 or newer.
 
-The examples use the default solver (CBC). To use other solvers they must be available (installed and accessible). For more information on how to do that, see the `guide on configuring solvers <https://coin-or.github.io/pulp/guides/how_to_configure_solvers.html>`_.
+The easiest way to install PuLP is with ``pip``. If ``pip`` is available on your system, type::
 
-Documentation
-================
+     python -m pip install pulp
 
-Documentation is found on https://coin-or.github.io/pulp/.
+Otherwise follow the download instructions on the `PyPi page <https://pypi.python.org/pypi/PuLP>`_.
 
 
-Use LpVariable() to create new variables. To create a variable 0 <= x <= 3::
+Quickstart 
+===============
 
+Use ``LpVariable`` to create new variables. To create a variable x with 0  ≤  x  ≤  3::
+
+     from pulp import *
      x = LpVariable("x", 0, 3)
 
-To create a variable 0 <= y <= 1::
+To create a binary variable, y, with values either 0 or 1::
 
-     y = LpVariable("y", 0, 1)
+     y = LpVariable("y", cat="Binary")
 
-Use LpProblem() to create new problems. Create "myProblem"::
+Use ``LpProblem`` to create new problems. Create a problem called "myProblem" like so::
 
      prob = LpProblem("myProblem", LpMinimize)
 
-Combine variables to create expressions and constraints, then add them to the
-problem::
+Combine variables in order to create expressions and constraints, and then add them to the problem.::
 
      prob += x + y <= 2
 
-If you add an expression (not a constraint), it will
-become the objective::
+An expression is a constraint without a right-hand side (RHS) sense (one of ``=``, ``<=`` or ``>=``). If you add an expression to a problem, it will become the objective::
 
      prob += -4*x + y
 
-To solve with the default included solver::
+To solve the problem  with the default included solver::
 
      status = prob.solve()
 
-To use another sovler to solve the problem::
+If you want to try another solver to solve the problem::
 
      status = prob.solve(GLPK(msg = 0))
 
@@ -86,26 +65,53 @@ Display the status of the solution::
      LpStatus[status]
      > 'Optimal'
 
-You can get the value of the variables using value(). ex::
+You can get the value of the variables using ``value``. ex::
 
      value(x)
      > 2.0
 
-Exported Classes:
 
-* ``LpProblem`` -- Container class for a Linear programming problem
-* ``LpVariable`` -- Variables that are added to constraints in the LP
-* ``LpConstraint`` -- A constraint of the general form
+Essential Classes
+------------------
+
+
+* ``LpProblem`` -- Container class for a Linear or Integer programming problem
+* ``LpVariable`` -- Variables that are added into constraints in the LP problem
+* ``LpConstraint`` -- Constraints of the general form
 
-      a1x1+a2x2 ...anxn (<=, =, >=) b
+      a1x1 + a2x2 + ... + anxn (<=, =, >=) b
 
-*  ``LpConstraintVar`` -- Used to construct a column of the model in column-wise modelling
+* ``LpConstraintVar`` -- A special type of constraint for constructing column of the model in column-wise modelling
 
-Exported Functions:
+Useful Functions
+------------------
 
 * ``value()`` -- Finds the value of a variable or expression
-* ``lpSum()`` -- given a list of the form [a1*x1, a2x2, ..., anxn] will construct a linear expression to be used as a constraint or variable
-* ``lpDot()`` --given two lists of the form [a1, a2, ..., an] and [ x1, x2, ..., xn] will construct a linear expression to be used as a constraint or variable
+* ``lpSum()`` -- Given a list of the form [a1*x1, a2*x2, ..., an*xn] will construct a linear expression to be used as a constraint or variable
+* ``lpDot()`` -- Given two lists of the form [a1, a2, ..., an] and [x1, x2, ..., xn] will construct a linear expression to be used as a constraint or variable
+
+More Examples
+================
+
+Several tutorial are given in `documentation <https://coin-or.github.io/pulp/CaseStudies/index.html>`_ and pure code examples are available in `examples/ directory <https://github.com/coin-or/pulp/tree/master/examples>`_ .
+
+The examples use the default solver (CBC). To use other solvers they must be available (installed and accessible). For more information on how to do that, see the `guide on configuring solvers <https://coin-or.github.io/pulp/guides/how_to_configure_solvers.html>`_.
+
+
+For Developers 
+================
+
+
+If you want to install the latest version from GitHub you can run::
+
+    python -m pip install -U git+https://github.com/coin-or/pulp
+
+
+On Linux and MacOS systems, you must run the tests to make the default solver executable::
+
+     sudo pulptest
+
+
 
 
 Building the documentation
@@ -126,17 +132,20 @@ To build, run the following in a terminal window, in the PuLP root directory
 A folder named html will be created inside the ``build/`` directory.
 The home page for the documentation is ``doc/build/html/index.html`` which can be opened in a browser.
 
+Contributing to PuLP
+-----------------------
+Instructions for making your first contribution to PuLP are given `here <https://coin-or.github.io/pulp/develop/contribute.html>`_.
 
-
-
-
-
-**Comments, bug reports, patches and suggestions are welcome.**
+**Comments, bug reports, patches and suggestions are very welcome!**
 
 * Comments and suggestions: https://github.com/coin-or/pulp/discussions
 * Bug reports: https://github.com/coin-or/pulp/issues
 * Patches: https://github.com/coin-or/pulp/pulls
 
+Copyright and License 
+=======================
+PuLP is distributed under an MIT license. 
+
      Copyright J.S. Roy, 2003-2005
      Copyright Stuart A. Mitchell
      See the LICENSE file for copyright information.

doc/source/CaseStudies/a_blending_problem.rst

@@ -1,3 +1,5 @@
+.. _blending_problem:
+
 A Blending Problem 
 ===================
 

doc/source/index.rst

@@ -6,14 +6,21 @@
 Optimization with PuLP
 ----------------------
 
-You can begin learning Python and using PuLP
-by looking at the content below. We recommend that you read The Optimisation Process,
-Optimisation Concepts, and the Introduction to Python
-before beginning the case-studies. For instructions for the installation of PuLP
-see :ref:`installation`.
-
-The full PuLP function documentation is available, and useful functions
-will be explained in the case studies.
+PuLP is an linear and mixed integer programming modeler written in Python.
+
+With PuLP, it is simple to create MILP optimisation problems and solve them with the
+latest open-source (or proprietary) solvers.  PuLP can generate MPS or LP files and
+call solvers such as GLPK_, COIN-OR CLP/`CBC`_, CPLEX_, GUROBI_, MOSEK_, XPRESS_,
+CHOCO_, MIPCL_, HiGHS_, SCIP_/FSCIP_.
+
+Here are some ways to get started using PuLP:
+
+* for instructions about installing PuLP see :ref:`installation`.
+* If you're new to Python and optimisation we recommend that you read :ref:`optimisation_concepts`, :ref:`optimisation_process`, and the :ref:`getting_started_with_python`. 
+* If you want to jump right in then start reading the case studies starting with :ref:`blending_problem`. 
+
+The full PuLP API documentation is available, and useful functions
+are also explained in the case studies.
 The case studies are in order, so the later case studies will assume you have
 (at least) read the earlier case studies. However, we will provide links to any
 relevant information you will need.
@@ -34,3 +41,16 @@ Authors
 The authors of this documentation (the pulp documentation team) include:
 
 .. include:: AUTHORS.txt
+
+
+.. _GLPK: http://www.gnu.org/software/glpk/glpk.html
+.. _CBC: https://github.com/coin-or/Cbc
+.. _CPLEX: http://www.cplex.com/
+.. _GUROBI: http://www.gurobi.com/
+.. _MOSEK: https://www.mosek.com/
+.. _XPRESS: https://www.fico.com/es/products/fico-xpress-solver
+.. _CHOCO: https://choco-solver.org/
+.. _MIPCL: http://mipcl-cpp.appspot.com/
+.. _SCIP: https://www.scipopt.org/
+.. _HiGHS: https://highs.dev
+.. _FSCIP: https://ug.zib.de

doc/source/main/basic_python_coding.rst

@@ -1,3 +1,6 @@
+.. _getting_started_with_python:
+
+
 Basic Python Coding
 ===================
 

doc/source/main/optimisation_concepts.rst

@@ -1,3 +1,5 @@
+.. _optimisation_concepts:
+
 Optimisation Concepts
 =====================
 

doc/source/main/the_optimisation_process.rst

@@ -1,3 +1,6 @@
+.. _optimisation_process:
+
+
 The Optimisation Process
 ========================