Adds support for mkdocs

Author: sebastian-quintero

.gitignore

@@ -161,3 +161,6 @@ cython_debug/
 
 # VSCode
 .vscode/
+
+# Documentation stuff
+site/

.markdownlint.jsonc

@@ -0,0 +1,51 @@
+// Reference: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
+// Rules: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#rules
+//
+// Run markdown linting:
+// - Install [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2):
+// npm install markdownlint-cli2 --global
+// - Lint. Stand at the root of the repo and run:
+// markdownlint-cli2 "**/*.md"
+// - Ignore a certain rule for some lines:
+// <!-- markdownlint-disable MD013 -->
+// Your line here
+// <!-- markdownlint-enable MD013 -->
+{
+  // Use the default configurations as a starting point
+  "default": true,
+
+  // Max line length configurations
+  "MD013": {
+    "code_blocks": false,
+    "headings": false,
+    "line_length": 100,
+    "stern": false,
+    "strict": false,
+    "tables": false
+  },
+
+  // GitBook compatibility configurations
+  // Unordered lists use asterisks
+  "MD004": { "style": "asterisk" },
+
+  // First line in a file should be a top-level heading specifying a
+  // description, as such:
+  // ---
+  // description: You will learn the basics of getting started on cloud.
+  // ---
+  "MD041": { "level": 1, "front_matter_title": "^\\s*description\\s*[:=]" },
+
+  // There can only be a single top-level heading, which should be the YAML
+  // front matter containing the "title" property.
+  "MD025": { "level": 1, "front_matter_title": "^\\s*title\\s*[:=]" },
+
+  // Don't enforce heading level continuity.
+  "MD001": false,
+
+  // Use spaces as opposed to hard-tabs for consistency.
+  "MD010": { "spaces_per_tab": 4 },
+
+  // Material for mkdocs has admonitions which are indented by 4 spaces and not
+  // fenced.
+  "MD046": false
+}

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/images/logo-180.png

@@ -0,0 +1,41 @@
+# The Nextmv Python SDKs
+
+Nextmv offers several Python SDKs to help you work with decision models and the
+Nextmv Cloud API:
+
+* [`nextmv`][nextmv]: The general-purpose Python SDK for working with decision
+      models and the Nextmv Cloud API.
+* [`nextmv-gurobipy`][nextmv-gurobipy]: A Python SDK providing convenience
+      functions for working with Gurobi (`gurobipy`) models in the Nextmv
+      platform.
+* [`nextmv-scikit-learn`][nextmv-scikit-learn]: A Python SDK providing
+      convenience functions for working with `scikit-learn` models in the
+      Nextmv platform.
+
+These packages can be found in the [`nextmv-py`][nextmv-py] repository.
+
+!!! warning
+
+    Please review the license of each package, as they may not all have the same
+    license. For example, `nextmv` is licensed under the Apache 2.0 license, while
+    `nextmv-gurobipy` is licensed as BSL-1.1.
+
+The best place to start with the Nextmv Python SDKs is to check out the
+[community apps][community-apps-get-started]. These are fully-functional apps
+that run both locally and on Nextmv Cloud. Please direct your attention to the
+`python-*` apps.
+
+There are two ways in which you can use community apps:
+
+* Go to the [`community-apps` GitHub repository][community-apps-gh]. You can
+  clone the repo, or view the apps directly in the GitHub UI.
+* Use the [Nextmv CLI][cli] to first list the available apps and clone them
+  locally. Check out the guide [here][community-apps-get-started].
+
+[nextmv-py]: https://github.com/nextmv-io/nextmv-py
+[nextmv]: ./nextmv/index.md
+[nextmv-gurobipy]: ./nextmv-gurobipy/index.md
+[nextmv-scikit-learn]: ./nextmv-scikit-learn/index.md
+[community-apps-gh]: https://github.com/nextmv-io/community-apps
+[cli]: https://docs.nextmv.io/docs/using-nextmv/reference/cli
+[community-apps-get-started]: https://docs.nextmv.io/docs/use-cases/community-apps/get-started

docs/images/nextmv-favicon.svg

@@ -0,0 +1,30 @@
+# Overview
+
+The [Nextmv & Gurobi Python SDK][nextmv-gurobipy], `nextmv-gurobipy`, is a
+package to interact programmatically with Nextmv and the Gurobi solver, from
+Python. A great way to get started is to check out the [community
+apps][community-apps-get-started]. The following apps are a non-exhaustive list
+of concrete examples for using this SDK:
+
+* [`python-nextmv-gurobipy-knapsack`][python-nextmv-gurobipy-knapsack]
+
+## Installation
+
+The package is hosted on [PyPI][nextmv-gurobipy-pypi]. Python `>=3.9` is
+required.
+
+Install via `pip`:
+
+```bash
+pip install nextmv-gurobipy
+```
+
+!!! tip
+
+    Note that `nextmv-gurobipy` installs the `nextmv_gurobipy` package, which is
+    the importable name for the SDK.
+
+[nextmv-gurobipy-pypi]: https://pypi.org/project/nextmv-gurobipy/
+[nextmv-gurobipy]: https://github.com/nextmv-io/nextmv-py/tree/develop/nextmv-gurobipy
+[community-apps-get-started]: https://docs.nextmv.io/docs/use-cases/community-apps/get-started
+[python-nextmv-gurobipy-knapsack]: https://github.com/nextmv-io/community-apps/blob/develop/python-nextmv-gurobipy-knapsack

docs/images/scenario-test.png

@@ -0,0 +1,5 @@
+# Model Module
+
+This section documents the model components of the Nextmv Gurobi Python SDK.
+
+::: nextmv-gurobipy.nextmv_gurobipy.model

docs/index.md

@@ -0,0 +1,5 @@
+# Options Module
+
+This section documents the options components of the Nextmv Gurobi Python SDK.
+
+::: nextmv-gurobipy.nextmv_gurobipy.options

docs/nextmv-gurobipy/index.md

@@ -0,0 +1,5 @@
+# Solution Module
+
+This section documents the solution components of the Nextmv Gurobi Python SDK.
+
+::: nextmv-gurobipy.nextmv_gurobipy.solution

docs/nextmv-gurobipy/reference/model.md

@@ -0,0 +1,5 @@
+# Statistics Module
+
+This section documents the statistics components of the Nextmv Gurobi Python SDK.
+
+::: nextmv-gurobipy.nextmv_gurobipy.statistics

docs/nextmv-gurobipy/reference/options.md

@@ -0,0 +1,100 @@
+# Model
+
+!!! tip "Reference"
+
+    Find the reference for the `model` module [here](../reference/model.md).
+
+`Model` allows you to create a `gurobipy.Model` object from `nextmv.Options`.
+This convenience function allows you to set up a Gurobi model using the
+parameters that are customized through options. Notice that the return type is
+a `gurobipy.Model`.
+
+Consider the following script, which solves a simple knapsack problem.
+
+```python
+import time
+
+import nextmv_gurobipy as ngp
+from gurobipy import GRB
+
+data = {
+    "items": [
+        {"id": "cat", "value": 100, "weight": 20},
+        {"id": "dog", "value": 20, "weight": 45},
+        {"id": "water", "value": 40, "weight": 2},
+        {"id": "phone", "value": 6, "weight": 1},
+        {"id": "book", "value": 63, "weight": 10},
+        {"id": "rx", "value": 81, "weight": 1},
+        {"id": "tablet", "value": 28, "weight": 8},
+        {"id": "coat", "value": 44, "weight": 9},
+        {"id": "laptop", "value": 51, "weight": 13},
+        {"id": "keys", "value": 92, "weight": 1},
+        {"id": "nuts", "value": 18, "weight": 4},
+    ],
+    "weight_capacity": 50,
+}
+
+options = ngp.ModelOptions().to_nextmv()
+start_time = time.time()
+model = ngp.Model(options)
+
+# Initializes the linear sums.
+weights = 0.0
+values = 0.0
+
+# Creates the decision variables and adds them to the linear sums.
+items = []
+for item in data["items"]:
+    item_variable = model.addVar(vtype=GRB.BINARY, name=item["id"])
+    items.append({"item": item, "variable": item_variable})
+    weights += item_variable * item["weight"]
+    values += item_variable * item["value"]
+
+# This constraint ensures the weight capacity of the knapsack will not be
+# exceeded.
+model.addConstr(weights <= data["weight_capacity"])
+
+# Sets the objective function: maximize the value of the chosen items.
+model.setObjective(expr=values, sense=GRB.MAXIMIZE)
+
+# Solves the problem.
+model.optimize()
+```
+
+Run the script with custom options:
+
+```bash
+python main.py -TimeLimit 1 -MIPGap 0.4
+...
+...
+
+Non-default parameters:
+TimeLimit  1
+MIPGap  0.4
+
+Optimize a model with 1 rows, 11 columns and 11 nonzeros
+Model fingerprint: 0x3fd9f770
+Variable types: 0 continuous, 11 integer (11 binary)
+Coefficient statistics:
+  Matrix range     [1e+00, 4e+01]
+  Objective range  [6e+00, 1e+02]
+  Bounds range     [1e+00, 1e+00]
+  RHS range        [5e+01, 5e+01]
+Found heuristic solution: objective 428.0000000
+
+Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+Thread count was 1 (of 10 available processors)
+
+Solution count 1: 428 
+
+Optimal solution found (tolerance 4.00e-01)
+Best objective 4.280000000000e+02, best bound 5.430000000000e+02, gap 26.8692%
+```
+
+Notice how the solver output states which options were customized. Using the
+`nextmv_gurobipy.Model` class has other added benefits, besides the convenience
+of customizing solver options:
+
+* It instantiates an empty environment.
+* It redirects `stdout` to `stderr` for logging in Nextmv Cloud.
+* It loads the license automatically if the `license_path` is given.