Documentation updates to sphinx

mggg · May 15, 2024 · 096b620 · 096b620
1 parent 78dfedb
commit 096b620
Show file tree

Hide file tree

Showing 35 changed files with 1,558 additions and 501 deletions.
diff --git a/.gitignore b/.gitignore
@@ -72,5 +72,9 @@ junit.xml
 # Editors
 .vscode/
 
+# Working environments
+.venv
+.docs_venv
+
 # Pytest cache
 .pytest_cache/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -17,9 +17,6 @@ sphinx:
    builder: dirhtml
    configuration: docs/conf.py
 
-# Optionally build your docs in additional formats such as PDF
-formats:
-   - pdf
 
 # Optionally set the version of Python and requirements required to build your docs
 python:

diff --git a/README.md b/README.md
@@ -253,19 +253,19 @@ So, out of 3,014 total Census blocks, 884 were not assigned to any old precinct
 >>> blocks.plot()
 ```
 
-![Providence blocks](./examples/Providence_blocks_plot.png)
+![Providence blocks](../_static/images/Providence_blocks_plot.png)
 
 ```python
 >>> old_precincts.plot()
 ```
 
-![Providence old precincts](./examples/Providence_old_precincts_plot.png)
+![Providence old precincts](../_static/images/Providence_old_precincts_plot.png)
 
 ```python
 >>> new_precincts.plot()
 ```
 
-![Providence new precincts](./examples/Providence_new_precincts_plot.png)
+![Providence new precincts](../_static/images/Providence_new_precincts_plot.png)
 
 The boundaries of the regions covered by these shapefiles are substantially 
 different---and that doesn't even get into the possibility that the precinct shapefiles may have gaps between precinct polygons that some blocks may fall into.
@@ -404,7 +404,7 @@ toy_precincts_df = geopandas.GeoDataFrame(geometry = geopandas.GeoSeries(ppolys)
 toy_precincts_df.plot(cmap = "tab20", alpha=0.7)
 ```
 
-![toy_precincts](./examples/toy_precincts.png)
+![toy_precincts](../_static/images/toy_precincts.png)
 
 Check for gaps and overlaps:
 ```python
@@ -420,7 +420,7 @@ toy_precincts_repaired_df = maup.smart_repair(toy_precincts_df)
 toy_precincts_repaired_df.plot(cmap = "tab20", alpha=0.7)
 ```
 
-![toy_precincts_repaired](./examples/toy_precincts_repaired.png)
+![toy_precincts_repaired](../_static/images/toy_precincts_repaired.png)
 
 We can check that the repair succeeded:
 ```python
@@ -440,35 +440,35 @@ toy_counties_df = geopandas.GeoDataFrame(geometry = geopandas.GeoSeries([cpoly1,
 
 toy_counties_df.plot(cmap='tab20')
 ```
-![toy_counties](./examples/toy_counties.png)
+![toy_counties](../_static/images/toy_counties.png)
 
 We can perform a "county-aware" repair as follows:
 ```python
 toy_precincts_repaired_county_aware_df = maup.smart_repair(toy_precincts_df, nest_within_regions = toy_counties_df)
 toy_precincts_repaired_county_aware_df.plot(cmap = "tab20", alpha=0.7)
 ```
-![toy_precincts_repaired_county_aware](./examples/toy_precincts_repaired_county_aware.png)
+![toy_precincts_repaired_county_aware](../_static/images/toy_precincts_repaired_county_aware.png)
 
 Next, suppose that we'd like to get rid of small rook adjacencies at corner points where 4 precincts meet.  We might reasonably estimate that these all have length less than $0.1$, so we can accomplish this as follows:
 ```python
 toy_precincts_repaired_county_aware_rook_to_queen_df = maup.smart_repair(toy_precincts_df, nest_within_regions = toy_counties_df, min_rook_length = 0.1)
 toy_precincts_repaired_county_aware_rook_to_queen_df.plot(cmap = "tab20", alpha=0.7)
 ```
-![toy_precincts_repaired_county_aware_rook_to_queen](./examples/toy_precincts_repaired_county_aware_rook_to_queen.png)
+![toy_precincts_repaired_county_aware_rook_to_queen](../_static/images/toy_precincts_repaired_county_aware_rook_to_queen.png)
 
 The difference is hard to see, so let's zoom in on gap between the 4 original precincts in the upper left-hand corner.
 
 Original precincts:
 
-![toy_precincts_corner](./examples/toy_precincts_corner.png)
+![toy_precincts_corner](../_static/images/toy_precincts_corner.png)
 
 County-aware repair:
 
-![toy_precincts_corner_repaired](./examples/toy_precincts_corner_repaired.png)
+![toy_precincts_corner_repaired](../_static/images/toy_precincts_corner_repaired.png)
 
 County-aware repair with rook adjacency converted to queen:
 
-![toy_precincts_corner_repaired_rook_to_queen](./examples/toy_precincts_corner_repaired_rook_to_queen.png)
+![toy_precincts_corner_repaired_rook_to_queen](../_static/images/toy_precincts_corner_repaired_rook_to_queen.png)
 
 
 ## Modifiable areal unit problem

diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,29 @@
+.download-badge {
+    display: inline-block;
+    padding: 8px 15px;
+    margin: 10px;
+    background-color: #0099CD;
+    color: white;
+    text-decoration: none;
+    border-radius: 5px;
+    font-size: 16px;
+}
+.download-badge:hover {
+    background-color: #2980B9;
+}
+
+.center-container {
+    text-align: center;
+    width: 100%;
+}
+
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+}
+th, td {
+    border: 1px solid #DDDDDD;
+    padding: 8px;
+    text-align: center;
+}
diff --git a/examples/Providence_blocks_plot.png → ..._static/images/Providence_blocks_plot.png b/examples/Providence_blocks_plot.png → ..._static/images/Providence_blocks_plot.png
diff --git a/examples/Providence_new_precincts_plot.png → .../images/Providence_new_precincts_plot.png b/examples/Providence_new_precincts_plot.png → .../images/Providence_new_precincts_plot.png
diff --git a/examples/Providence_old_precincts_plot.png → .../images/Providence_old_precincts_plot.png b/examples/Providence_old_precincts_plot.png → .../images/Providence_old_precincts_plot.png
diff --git a/docs/_static/images/output_22_0.png b/docs/_static/images/output_22_0.png
diff --git a/docs/_static/images/output_23_0.png b/docs/_static/images/output_23_0.png
diff --git a/docs/_static/images/output_30_0.png b/docs/_static/images/output_30_0.png
diff --git a/docs/_static/images/output_40_0.png b/docs/_static/images/output_40_0.png
diff --git a/examples/plot.png → docs/_static/images/plot.png b/examples/plot.png → docs/_static/images/plot.png
diff --git a/examples/plot_without_gaps.png → docs/_static/images/plot_without_gaps.png b/examples/plot_without_gaps.png → docs/_static/images/plot_without_gaps.png
diff --git a/examples/plot_without_gaps_or_overlaps.png → .../images/plot_without_gaps_or_overlaps.png b/examples/plot_without_gaps_or_overlaps.png → .../images/plot_without_gaps_or_overlaps.png
diff --git a/examples/toy_counties.png → docs/_static/images/toy_counties.png b/examples/toy_counties.png → docs/_static/images/toy_counties.png
diff --git a/examples/toy_precincts.png → docs/_static/images/toy_precincts.png b/examples/toy_precincts.png → docs/_static/images/toy_precincts.png
diff --git a/examples/toy_precincts_corner.png → docs/_static/images/toy_precincts_corner.png b/examples/toy_precincts_corner.png → docs/_static/images/toy_precincts_corner.png
diff --git a/examples/toy_precincts_corner_repaired.png → .../images/toy_precincts_corner_repaired.png b/examples/toy_precincts_corner_repaired.png → .../images/toy_precincts_corner_repaired.png
diff --git a/...ecincts_corner_repaired_rook_to_queen.png → ...ecincts_corner_repaired_rook_to_queen.png b/...ecincts_corner_repaired_rook_to_queen.png → ...ecincts_corner_repaired_rook_to_queen.png
diff --git a/examples/toy_precincts_repaired.png → ..._static/images/toy_precincts_repaired.png b/examples/toy_precincts_repaired.png → ..._static/images/toy_precincts_repaired.png
diff --git a/...s/toy_precincts_repaired_county_aware.png → ...s/toy_precincts_repaired_county_aware.png b/...s/toy_precincts_repaired_county_aware.png → ...s/toy_precincts_repaired_county_aware.png
diff --git a/...s_repaired_county_aware_rook_to_queen.png → ...s_repaired_county_aware_rook_to_queen.png b/...s_repaired_county_aware_rook_to_queen.png → ...s_repaired_county_aware_rook_to_queen.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,9 +13,15 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
-print(f"The system path is {sys.path}")
 
 
+
+# Add markdown parser
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
 # -- Project information -----------------------------------------------------
 
 project = 'maup'
@@ -32,15 +38,14 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'myst_parser', 
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    'numpydoc',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx_copybutton',
 ]
 
 # apidoc
@@ -57,23 +62,42 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+pygments_style = 'sphinx'
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "pydata_sphinx_theme"
-html_theme_options = {
-    "github_url": "https://github.com/mggg/maup",
-    "show_prev_next": False,
-    "navbar_end": ["search-field.html", "navbar-icon-links.html"],
-}
-html_sidebars = {
-    "**": [],
-}
+html_theme = "sphinx_rtd_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {"style_nav_header_background": "#0099cd"}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ["_static"]
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+html_css_files = [
+    'css/custom.css',
+]
+
+
+# -- Extension configuration -------------------------------------------------
+
+# Prepend the module name of classes.
+add_module_names = True
+autodoc_inherit_docstrings = False
diff --git a/docs/full_ref.rst b/docs/full_ref.rst
@@ -0,0 +1,100 @@
+Full Package Reference
+======================
+
+This page contains the full reference for the ``maup`` package, and
+is included primarily for the sake of developers trying to hunt down errors
+or understand the codebase. 
+
+
+.. automodule:: maup
+
+
+Adjacencies
+-----------
+
+.. automodule:: maup.adjacencies
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Assign
+------
+
+.. automodule:: maup.assign
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+CRS
+---
+
+.. automodule:: maup.crs
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Indexed Geometries
+------------------
+
+.. automodule:: maup.indexed_geometries
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Indices
+-------
+
+.. automodule:: maup.indices
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Intersections
+-------------
+
+.. automodule:: maup.intersections
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Normalize
+---------
+
+.. automodule:: maup.normalize
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Progress Bar
+------------
+
+.. automodule:: maup.progress_bar
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Repair
+------
+
+.. automodule:: maup.repair
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex:
+
+Smart Repair
+------------
+
+.. automodule:: maup.smart_repair
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :noindex: