WIP: update documentation structure

docs/source/howto.rst

@@ -0,0 +1,11 @@
+How-To Guides
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: How To ...
+
+   Avoid Performance Pitfalls <performance>
+   Add Specialized Constraints <advanced>
+   Name Variables and Constraints <naming>
+   Use Type Hinting <typing>

docs/source/index.rst

@@ -1,40 +1,70 @@
-Welcome to gurobipy-pandas's documentation!
-===========================================
+gurobipy-pandas documentation
+=============================
 
-``gurobipy-pandas`` is a convenient (optional) wrapper to connect pandas with gurobipy. It enables users to more easily and efficiently build mathematical optimization models from data stored in DataFrames and Series, and to read solutions back directly as pandas objects.
+``gurobipy-pandas`` is a convenient (optional) wrapper to connect
+:pypi:`pandas` with :pypi:`gurobipy`. It enables users to more easily
+and efficiently build mathematical optimization models from data stored
+in DataFrames and Series, and to read solutions back directly as pandas
+objects.
 
-``gurobipy-pandas`` is aimed at experienced pandas users who are familiar with methods to transform, group, and aggregate data stored in dataframes. It expects some familiarity with optimization modelling, but does not require deep experience with gurobipy.
+``gurobipy-pandas`` is aimed at experienced pandas users who are
+familiar with methods to transform, group, and aggregate data stored in
+dataframes. It expects some familiarity with optimization modelling, but
+does not require deep experience with gurobipy.
 
-Getting Started
----------------
+Installation
+------------
 
-``gurobipy-pandas`` provides simple to use functions and pandas accessors to help build optimization models and query solutions. Read the :doc:`usage` page first for an overview of the key methods. Second, explore the :doc:`examples` which provide complete model implementations formatted as Jupyter notebooks. The later sections cover advanced techniques, and advice on writing clean and performant model building code using this library.
+:code:`gurobipy-pandas` can be installed directly from PyPI::
 
-Documentation
--------------
+   python -m pip install gurobipy-pandas
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Start
+This will also install pandas and gurobipy as dependencies.
 
-   installation
-   usage
-   examples
+Please note that gurobipy is commercial software and requires a license.
+The package ships with an evaluation license which is only for testing
+and can only solve models of limited size. You will be able to run all
+the examples given in this documentation using this evaluation license.
+
+A Simple Example
+----------------
+
+Build a simple optimization model!
+
+How to Use this Documentation
+-----------------------------
+
+``gurobipy-pandas`` provides simple to use functions and pandas
+accessors to help build optimization models and query solutions. Read
+the :doc:`usage` page first for an overview of the key methods. Second,
+explore the :doc:`examples` which provide complete model implementations
+formatted as Jupyter notebooks. The :doc:`howto` cover methods for
+specific use-cases and provide advice on writing clean and performant
+model building code using this library. The :doc:`api` provides complete
+reference documentation for the library.
+
+Contact Us
+----------
+
+For questions related to using gurobipy-pandas please use the
+`Gurobi Community Forum <https://support.gurobi.com/hc/en-us/community/topics/10373864542609-GitHub-Projects>`_.
+
+For reporting bugs, issues and feature requests, specific to ``gurobipy-pandas``, please
+`open an issue <https://github.com/Gurobi/gurobipy-pandas/issues>`_.
+
+If you encounter issues with Gurobi or ``gurobipy`` please contact
+`Gurobi Support <https://support.gurobi.com/hc/en-us>`_.
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Model Building
 
-   performance
-   naming
-   advanced
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Reference
+   :hidden:
 
+   installation
+   usage
+   examples
+   How To ... <howto>
    api
-   typing
    license
    contact
    acknowledgements

docs/source/naming.rst

@@ -1,5 +1,5 @@
-Variable & Constraint Naming
-============================
+Variable & Constraint Names
+===========================
 
 It's good practice to name variables and constraints in optimization models. One good reason is that once a model is formulated from a dataset, you can write it to LP format for checking and debugging purposes.
 

docs/source/typing.rst

@@ -1,6 +1,12 @@
-Typing
-======
+Type Hints
+==========
 
-The ``gurobipy-pandas`` API is partially typed. There is currently no mechanism in Python's type system to allow for type checking of the DataFrame or Series accessor methods. So, it is only possible to get type checking in your IDE, or static type checking with tools like ``mypy`` if you use the free functions ``gppd.add_vars`` and ``gppd.add_constrs`` when building your model.
+The ``gurobipy-pandas`` API is partially typed. There is currently no
+mechanism in Python's type system to allow for type checking of the
+DataFrame or Series accessor methods. So, it is only possible to get
+type checking in your IDE, or static type checking with tools like
+``mypy`` if you use the global functions ``gppd.add_vars`` and
+``gppd.add_constrs`` when building your model.
 
-To enable type checking, you should also install ``pandas-stubs`` and ``gurobipy-stubs`` in your Python environment.
+To enable type checking, you will also need to install
+:pypi:`pandas-stubs` in your Python environment.

docs/source/usage.rst

@@ -1,5 +1,5 @@
-Usage
-=====
+Tutorial
+========
 
 This page gives a brief run through of methods used to build optimization models in ``gurobipy-pandas`` and extract solutions. ``gurobipy-pandas`` provides several free functions for model building, and implements pandas' `accessors <https://pandas.pydata.org/docs/ecosystem.html#accessors>`_ to facilitate building models and querying results from dataframes and series respectively.