Merge pull request #17 from brightway-lca/documentation_upgrade

Major Documentation Upgrade

.readthedocs.yaml

@@ -15,6 +15,6 @@ submodules:
    include: all 
 
 build:
-   os: ubuntu-22.04 # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os
+   os: "ubuntu-lts-latest" # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os
    tools:
-      python: "mambaforge-4.10" # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python, mamba instead of conda for better build performance
+      python: "mambaforge-latest" # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python, mamba instead of conda for better build performance

CHANGES.md

@@ -1,4 +1,4 @@
-# bw_graph_tools Changelog
+# `bw_graph_tools` Changelog
 
 All notable changes to this project will be documented in this file.
 

README.md

@@ -44,7 +44,6 @@ Normally we construct matrices and solve the resulting set of linear equations t
 If we add temporal information using `bw_temporalis`, then the same node can occur at different times depending on how the temporal dynamics its preceding path. For example:
 
 
-
 ## Contributing
 
 Contributions are very welcome.
@@ -62,15 +61,9 @@ please [file an issue] along with a detailed description.
 
 ## Documentation
 
-1. Install the `sphinx-furo` conda environment from the file `.docs/environment.yml`.
-2. Build the documentation locally by running
+1. Install the conda environment from the file `.docs/environment.yml`
+2. Build the documentation locally by running:
 
-```
+```bash
 sphinx-autobuild docs _build/html -a -j auto --open-browser
-```
-
-<!-- github-only -->
-
-[command-line reference]: https://bw_graph_tools.readthedocs.io/en/latest/usage.html
-[license]: https://github.com/brightway-lca/bw_graph_tools/blob/main/LICENSE
-[contributor guide]: https://github.com/brightway-lca/bw_graph_tools/blob/main/CONTRIBUTING.md
+```

bw_graph_tools/graph_traversal.py

@@ -240,8 +240,8 @@ def calculate(
             traverse
         functional_unit_unique_id : int
             An integer id we can use for the functional unit virtual activity.
-            Shouldn't overlap any other activity ids. Don't change unless you r
-            eally know what you are doing.
+            Shouldn't overlap any other activity ids. Don't change unless you 
+            really know what you are doing.
 
         Returns
         -------

docs/conf.py

@@ -1,23 +1,15 @@
 ### import setup ##################################################################################
 
 import datetime
-import importlib.metadata
-import os
-import shutil
-from sphinx.ext import apidoc
 
 ### project information ###########################################################################
 
-project = "bw_graph_tools"
-author = "Chris Mutel"
-copyright = datetime.date.today().strftime("%Y") + ' Chris Mutel'
+project = "Brightway Graph Tools"
+author = "Brightway Developers"
+copyright = datetime.date.today().strftime("%Y") + ' Brightway Developers'
 
 ### project configuration #########################################################################
 
-needs_sphinx = '5.3.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     # native extensions
     'sphinx.ext.autodoc',
@@ -27,17 +19,44 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
     'sphinx.ext.napoleon',
+    # theme
+    'sphinx_rtd_theme',
     # Markdown support
     'myst_parser',
     # API documentation support
     'autoapi',
+    # responsive web component support
+    'sphinx_design',
+    # copy button on code blocks
+    "sphinx_copybutton",
 ]
 
 exclude_patterns = ['_build']
 
 # The master toctree document.
 master_doc = 'index'
 
+### theme configuration ############################################################################
+
+html_theme = "sphinx_rtd_theme"
+html_title = "Brightway Graph Tools"
+html_show_sphinx = False
+
+html_theme_options = {
+    'logo_only': False,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
+
+html_logo = 'https://raw.githubusercontent.com/brightway-lca/brightway-documentation/main/source/_static/logo/BW_all_white_transparent_landscape_wide.svg'
+html_favicon = 'https://github.com/brightway-lca/brightway-documentation/blob/main/source/_static/logo/BW_favicon_500x500.png'
+
 ### extension configuration ########################################################################
 
 ## myst_parser configuration ############################################
@@ -67,12 +86,11 @@
     'show-module-summary',
     #'special-members',
     #'imported-members',
-    'show-inheritance-diagram'
 ]
 
 autoapi_python_class_content = 'both'
 autoapi_member_order = 'groupwise'
-autoapi_root = 'pages/api'
+autoapi_root = 'content/api'
 autoapi_keep_files = False
 
 autoapi_dirs = [

docs/content/usage.md

@@ -0,0 +1,18 @@
+# Usage
+
+`bw_graph_tools` has three main components: A graph traversal class `NewNodeEachVisitGraphTraversal`; a function to guess production exchanges using only `bw_processing` datapackages `guess_production_exchanges`; and a function to find the path from node `A` to node `B` with the largest amount of the reference product of `A`, `get_path_from_matrix` and it's sister `path_as_brightway_objects`.
+
+### `NewNodeEachVisitGraphTraversal`
+
+Normally we construct matrices and solve the resulting set of linear equations to get a life cycle inventory or impact assessment result. The matrix approach is elegant, in that it simultaneously solves all equations and handles cycles in the graph, and much faster than graph traversal. However, in some cases we want to actually traverse the supply chain graph and calculate the individual impact of visiting nodes at that point in the graph. Graph traversal's use cases include:
+
+* Distinguishing between different paths to the same object
+* Convolving temporal distributions
+
+If we add temporal information using `bw_temporalis`, then the same node can occur at different times depending on how the temporal dynamics its preceding path. For example:
+
+## Some Examples
+
+- [`1 - Spatiotemporal calculations.ipynb`](https://github.com/brightway-lca/from-the-ground-up/blob/327e2af95249135a71a57cfb3eb0c7d73f6e5239/spatiotemporal/1%20-%20Spatiotemporal%20calculations.ipynb#L16)
+- [`1 - Introduction.ipynb`](https://github.com/brightway-lca/from-the-ground-up/blob/327e2af95249135a71a57cfb3eb0c7d73f6e5239/temporal/1%20-%20Introduction.ipynb#L215)
+- [`Example usage.ipynb`](https://github.com/brightway-lca/bw_temporalis/blob/911a7729d5ac065bbae862df5c1381aa1058cf48/dev/Example%20usage.ipynb#L17)

docs/environment.yaml

@@ -0,0 +1,20 @@
+name: sphinx_bw_graph_tools
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  # core functionality
+  - python
+  - ipython
+  # sphinx
+  - sphinx # core builder # https://anaconda.org/conda-forge/sphinx/files
+  # theme and extensions
+  - sphinx_rtd_theme # theme # https://anaconda.org/conda-forge/sphinx_rtd_theme/files
+  - myst-parser # Markdown support # https://anaconda.org/conda-forge/myst-parser/files
+  - sphinx-design # responsive web component support # https://anaconda.org/conda-forge/sphinx-design/files
+  - sphinx-copybutton # for copy button in code blocks # https://anaconda.org/conda-forge/sphinx-copybutton/files
+  - sphinx-autoapi # to build docs from source code instead of package import # https://anaconda.org/conda-forge/sphinx-autoapi/files
+  - sphinx-notfound-page # custom 404 page # https://anaconda.org/conda-forge/sphinx-notfound-page/files
+  - sphinx-copybutton # for copy button in code blocks # https://anaconda.org/conda-forge/sphinx-copybutton/files
+  # build process
+  - sphinx-autobuild # live-html support # https://anaconda.org/conda-forge/sphinx-autobuild/files

docs/index.md

@@ -1,24 +1,22 @@
-```{include} ../README.md
----
-end-before: <!-- github-only -->
----
-```
+# Brightway Graph Tools
 
-[license]: license
-[contributor guide]: contributing
-[command-line reference]: usage
-[changelog]: changelog
+```{button-link} https://docs.brightway.dev
+:color: info
+:expand:
+:click-parent:
+{octicon}`light-bulb;1em` Brightway Graph Tools is a specialized package of the Brightway Software Framework
+```
 
 ```{toctree}
 ---
 hidden:
 maxdepth: 1
 ---
-
-pages/usage
-Reference <pages/api>
-pages/contributing
-Code of Conduct <pages/codeofconduct>
-License <pages/license>
-Changelog <pages/changelog>
-```
+self
+content/usage
+content/api
+content/changelog
+content/contributing
+content/codeofconduct
+content/license
+```