start of doc work – focusing on locate docs

.ci/310.yaml

@@ -23,6 +23,6 @@ dependencies:
   # docs
   - nbsphinx
   - numpydoc
-  - sphinx
+  - sphinx<=4.5.0
   - sphinxcontrib-bibtex
   - sphinx_bootstrap_theme

.ci/39.yaml

@@ -20,9 +20,3 @@ dependencies:
   - pytest
   - pytest-cov
   - pytest-xdist
-  # docs
-  - nbsphinx
-  - numpydoc
-  - sphinx
-  - sphinxcontrib-bibtex
-  - sphinx_bootstrap_theme

.github/workflows/build_docs.yml

@@ -19,7 +19,7 @@
      strategy:
        matrix:
          os: ['ubuntu-latest']
-         environment-file: [.ci/39.yaml]
+         environment-file: [.ci/310.yaml]
          experimental: [false]
      defaults:
        run:

README.md

@@ -39,31 +39,25 @@ mexico.plot(column="maxp_new", categorical=True, figsize=(12,8), ec="w");
 
 ### Locate
 ```python
-from spopt.locate.coverage import MCLP
+from spopt.locate import MCLP
 from spopt.locate.util import simulated_geo_points
-import numpy
-import geopandas
-import pulp
-import spaghetti
+import numpy, geopandas, pulp, spaghetti
 
-solver = pulp.PULP_CBC_CMD(msg=False)
+solver = pulp.PULP_CBC_CMD(msg=False, warmStart=True)
 lattice = spaghetti.regular_lattice((0, 0, 10, 10), 9, exterior=True)
 ntw = spaghetti.Network(in_data=lattice)
 street = spaghetti.element_as_gdf(ntw, arcs=True)
 street_buffered = geopandas.GeoDataFrame(
-    geopandas.GeoSeries(street["geometry"].buffer(0.2).unary_union),
+    geopandas.GeoSeries(street["geometry"].buffer(0.5).unary_union),
     crs=street.crs,
     columns=["geometry"],
 )
-client_points = simulated_geo_points(street_buffered, needed=CLIENT_COUNT, seed=CLIENT_SEED)
-facility_points = simulated_geo_points(
-    street_buffered, needed=FACILITY_COUNT, seed=FACILITY_SEED
-)
+client_points = simulated_geo_points(street_buffered, needed=100, seed=5)
 ntw.snapobservations(client_points, "clients", attribute=True)
 clients_snapped = spaghetti.element_as_gdf(
     ntw, pp_name="clients", snapped=True
 )
-
+facility_points = simulated_geo_points(street_buffered, needed=10, seed=6)
 ntw.snapobservations(facility_points, "facilities", attribute=True)
 facilities_snapped = spaghetti.element_as_gdf(
     ntw, pp_name="facilities", snapped=True
@@ -72,11 +66,14 @@ cost_matrix = ntw.allneighbordistances(
     sourcepattern=ntw.pointpatterns["clients"],
     destpattern=ntw.pointpatterns["facilities"],
 )
-mclp_from_cost_matrix = MCLP.from_cost_matrix(cost_matrix, ai, MAX_COVERAGE, p_facilities=P_FACILITIES)
+numpy.random.seed(0)
+ai = numpy.random.randint(1, 12, 100)
+mclp_from_cost_matrix = MCLP.from_cost_matrix(cost_matrix, ai, 4, p_facilities=4)
 mclp_from_cost_matrix = mclp_from_cost_matrix.solve(solver)
 ```
+*see [notebook](https://github.com/pysal/spopt/blob/main/notebooks/mclp.ipynb) for plotting code*
 <p align="center">
-<img src="docs/_static/images/mclp.svg" height="350" />
+<img src="docs/_static/images/mclp.png" height="350" />
 </p>
 
 ## Examples

docs/conf.py

@@ -65,7 +65,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -86,7 +86,7 @@
 # html_theme = 'alabaster'
 html_theme = "bootstrap"
 html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
-html_title = "%s v%s Manual" % (project, version)
+html_title = f"{project} v{version} Manual"
 
 # (Optional) Logo of your package. Should be small enough to fit the navbar (ideally 24x24).
 # Path should be relative to the ``_static`` files directory.
@@ -161,7 +161,7 @@
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "%sdoc" % project
+htmlhelp_basename = f"{project}doc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -187,9 +187,9 @@
 latex_documents = [
     (
         master_doc,
-        "%sdoc.tex" % project,
-        "%s Documentation" % project,
-        "%s developers" % project,
+        f"{project}doc.tex",
+        f"{project} Documentation",
+        f"{project} developers",
         "manual",
     )
 ]
@@ -199,7 +199,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, project, "%s Documentation" % project, [author], 1)]
+man_pages = [(master_doc, project, f"{project} Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -211,7 +211,7 @@
     (
         master_doc,
         project,
-        "%s Documentation" % project,
+        f"{project} Documentation",
         author,
         project,
         "Spatial Optimization with PySAL",
@@ -248,16 +248,16 @@ def setup(app):
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "esda": ("https://pysal.org/esda/", None),
-    "geopandas": ("https://geopandas.readthedocs.io/en/latest/", None),
+    "geopandas": ("https://geopandas.org/en/latest/", None),
     "giddy": ("https://giddy.readthedocs.io/en/latest/", None),
     "hdbscan": ("https://hdbscan.readthedocs.io/en/latest/", None),
     "libpysal": ("https://pysal.org/libpysal/", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "pulp": ("https://coin-or.github.io/pulp/", None),
-    "python": ("https://docs.python.org/3.9/", None),
+    "python": ("https://docs.python.org/3.11/", None),
     "region": ("https://region.readthedocs.io/en/latest/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "sklearn": ("https://scikit-learn.org/stable/", None),
 }
 
@@ -318,6 +318,6 @@ def setup(app):
     "--InlineBackend.rc={'figure.dpi': 96}",
 ]
 
-mathjax_config = {
+mathjax3_config = {
     "TeX": {"equationNumbers": {"autoNumber": "AMS", "useLabelIds": True}},
 }

docs/index.rst

@@ -44,12 +44,32 @@ Regionalization, facility location, and transportation-oriented modeling
                 </div>
             </a>
         </div>
+        <div class="col-sm-4 col-xs-14">
+            <a href="https://pysal.org/spopt/notebooks/lscp_gis.html" class="thumbnail">
+                <img src="_static/images/notebooks-lscp.png"
+                class="img-responsive center-block">
+                <div class="caption text-center">
+                <h6>Locating First Aid Stations in Toronto
+                </h6>
+                </div>
+            </a>
+        </div>
         <div class="col-sm-4 col-xs-14">
             <a href="https://pysal.org/spopt/notebooks/facloc-real-world.html" class="thumbnail">
                 <img src="_static/images/notebooks-facloc-mclp.png"
                 class="img-responsive center-block">
                 <div class="caption text-center">
-                <h6>Locate Store Sites in San Francisco
+                <h6>Locating Store Sites in San Francisco
+                </h6>
+                </div>
+            </a>
+        </div>
+        <div class="col-sm-4 col-xs-14">
+            <a href="https://pysal.org/spopt/notebooks/lscpb.html" class="thumbnail">
+                <img src="_static/images/lscpb-predef.png"
+                class="img-responsive center-block">
+                <div class="caption text-center">
+                <h6>Backup Coverage and Predefined Locations
                 </h6>
                 </div>
             </a>

docs/installation.rst

@@ -3,8 +3,8 @@
 Installation
 ============
 
-spopt supports Python 3.7, 3.8, 3.9, and 3.10. Please make sure that you are
-operating in a Python >= 3.7 environment.
+spopt supports Python 3.8_, 3.9_, and 3.10_. Please make sure that you are
+operating in a Python >= 3.8 environment.
 
 Installing released version
 ---------------------------
@@ -43,6 +43,9 @@ your fork. By making changes
 to your local clone and submitting a pull request to `pysal/spopt`_, you can
 contribute to spopt development.
 
+.. _3.8: https://docs.python.org/3.8/
+.. _3.9: https://docs.python.org/3.9/
+.. _3.10: https://docs.python.org/3.10/
 .. _Python Package Index: https://pypi.org/project/spopt/
 .. _pysal/spopt: https://github.com/pysal/spopt
 .. _fork: https://help.github.com/articles/fork-a-repo/ 

docs/tutorials.rst

@@ -13,6 +13,8 @@ Tutorials
     notebooks/randomregion.ipynb
     notebooks/component_policy.ipynb
 
+.. toctree::
+    :maxdepth: 1
     :caption: Locate:
 
     notebooks/facloc-real-world.ipynb