Merge branch 'main' into bayesian-fit

docs/conf.py

@@ -18,10 +18,14 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "myst_nb",
+    "nbsphinx",
+    "myst_parser",
     "autoapi.extension",
+    "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx_design",
 ]
 autoapi_dirs = ["../src"]
 autoapi_options = [
@@ -52,4 +56,4 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"

docs/flow.ipynb

@@ -1,11 +1,12 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "f324071c",
    "metadata": {},
    "source": [
-    "# Simulating gas flow\n",
+    "# Gas Flow Simulation\n",
     "\n",
     "With `bluebonnet.flow`, you can solve pseudopressure over time and calculate how production declines and recovery factor increases. First, a few imports:"
    ]
@@ -45,6 +46,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "00072c90",
    "metadata": {},
@@ -108,6 +110,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "dfd552a8",
    "metadata": {},
@@ -246,7 +249,7 @@
     "    ylim=(0, None),\n",
     "    xscale=\"squareroot\",\n",
     "    xlim=(0, None),\n",
-    ")"
+    ");"
    ]
   },
   {
@@ -271,6 +274,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "558be95b-3eb7-4799-bbc3-cb8834000168",
    "metadata": {},

docs/forecast_varying.ipynb

@@ -6,19 +6,11 @@
    "id": "f324071c",
    "metadata": {},
    "source": [
-    "# Varying Fracface Pressure\n",
+    "# Fitting with Varying Fracface Pressure\n",
     "\n",
     "More advanced use of `bluebonnet.flow` in a project where pressure variation at the frac-face or bottom-hole is approximately known.\n",
     "\n",
-    "You can download and run this notebook with jupyter by clicking on the \"Edit on github\" button in the upper right corner. Then, install `bluebonnet` with\n",
-    "```sh\n",
-    "pip install bluebonnet\n",
-    "```\n",
-    "or inside the notebook with\n",
-    "```\n",
-    "%pip install bluebonnet\n",
-    "```\n",
-    "and follow below"
+    "First, import the necessary libraries"
    ]
   },
   {

docs/index.md

@@ -1,19 +1,99 @@
-```{include} ../README.md
+# Introduction to bluebonnet
 
+## Installation
+
+Run the command
+
+```bash
+pip install bluebonnet
 ```
 
+## Usage
+
+`bluebonnet` has a collection of tools for performing reservoir simulation in
+tight oil and shale gas reservoirs. The main tools are:
+
+1. `fluids` for modeling PVT and viscosity of oil, water, and gas;
+2. `flow` for building physics-based production curves; and
+3. `forecast` for fitting and forecasting unconventional production.
+
 ```{toctree}
 :maxdepth: 1
-:hidden:
+getting_started.ipynb
+```
+
+## What makes bluebonnet unique?
+
+The goal for this package is to make it easier to forecast production from
+hydrofractured wells. It uses semi-universal recovery factor scaling curves
+scaled by drainage volume and time-to-BDF to achieve these feats. These methods
+have been used to make forecasts from the individual well level up to the basin
+and play level, depending on the availability of fluid property and bottomhole
+pressure data.
+
+Compare to the most common unconventional production analysis tool. Emprical
+decline curve analysis (DCA) provides very fast answers, but lack physical
+meaning. Bluebonnet fits include estimates of the resource within the drainage
+volume and of permeability divided by interfracture spacing. A completion
+program purporting to increase the size of the fractured area can be tested with
+bluebonnet without requiring extensive 3D reservoir simulations.
+
+Also, bluebonnet naturally handles flow transitions, unlike DCA and type curves.
+Arps, for instance, has to have multiple segments stitched together to capture
+well behavior after the start of boundary dominated flow.
+
+Sometimes, 3-D reservoir simulation is absolutely necessary to understand the
+flow patterns around unconventional wells. However, due to the symmetries
+inherent in such flow and the independence of production between neighboring
+wells, one-dimensional methods like bluebonnet cover many of these use-cases.
+
+# How-to Guides
+
+Bluebonnet is extremely customizable. You can mix and match your fluid
+properties, relative permeabilities, and fitting functions to your heart's
+content.
+
+```{note}
+Bluebonnet will allow you to cut yourself. Want recovery factors greater
+than one? Fluids that behave in unphysical ways? Reservoir pressures lower than bottomhole pressure? You bet! Want negative
+Brooks-Corey exponents? Okay, that's a bridge too far, but you get the idea.
+```
+
+These how-to guides are here to help you mix and match and fine-tune your
+models.
+
+```{toctree}
+:maxdepth: 2
 fluids.ipynb
 flow.ipynb
 oil_flow.ipynb
 forecast.ipynb
 forecast_varying.ipynb
 bayesian_fitting.ipynb
+```
+
+# The API
+
+In depth API documentation for every function and class is here:
+
+```{toctree}
+:maxdepth: 4
 autoapi/index
+```
+
+# Theory and background
+
+```{toctree}
+background.md
+```
+
+# Developer information
+
+Interested in extending or contributing to this project? Read these:
+
+```{toctree}
+:maxdepth: 2
 contributing.md
 conduct.md
-background.md
 changelog.md
 ```

docs/oil_flow.ipynb

@@ -45,6 +45,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "dfd552a8",
    "metadata": {
@@ -204,6 +205,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "888126b3",
    "metadata": {},
@@ -292,6 +294,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "13d20050",
    "metadata": {},
@@ -346,6 +349,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "a7cae28e",
    "metadata": {},

noxfile.py

@@ -1,6 +1,7 @@
 """Nox sessions for linting, docs, and testing."""
 from __future__ import annotations
 
+import argparse
 import os
 import shutil
 from pathlib import Path
@@ -29,19 +30,46 @@ def tests(session: nox.Session) -> None:
     session.run("pytest", *session.posargs)
 
 
-@nox.session
+@nox.session(reuse_venv=True)
 def docs(session: nox.Session) -> None:
-    """Build the docs. Pass "serve" to serve."""
-    session.install(".[docs]")
+    """
+    Build the docs. Pass "--serve" to serve. Pass "-b linkcheck" to check links.
+    """
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--serve", action="store_true", help="Serve after building")
+    parser.add_argument(
+        "-b", dest="builder", default="html", help="Build target (default: html)"
+    )
+    args, posargs = parser.parse_known_args(session.posargs)
+
+    if args.builder != "html" and args.serve:
+        session.error("Must not specify non-HTML builder with --serve")
+
+    extra_installs = ["sphinx-autobuild"] if args.serve else []
+
+    session.install("-e.[docs]", *extra_installs)
     session.chdir("docs")
-    session.run("sphinx-build", "-M", "html", ".", "_build")
-
-    if session.posargs:
-        if "serve" in session.posargs:
-            print("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
-            session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
-        else:
-            session.warn("Unsupported argument to docs")
+
+    if args.builder == "linkcheck":
+        session.run(
+            "sphinx-build", "-b", "linkcheck", ".", "_build/linkcheck", *posargs
+        )
+        return
+
+    shared_args = (
+        "-n",  # nitpicky mode
+        "-T",  # full tracebacks
+        f"-b={args.builder}",
+        ".",
+        f"_build/{args.builder}",
+        *posargs,
+    )
+
+    if args.serve:
+        session.run("sphinx-autobuild", *shared_args)
+    else:
+        session.run("sphinx-build", "--keep-going", *shared_args)
 
 
 @nox.session