diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7c61239..898df34 100644 --- a/.readthedocs.yaml +++ b/.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 \ No newline at end of file + python: "mambaforge-latest" # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python, mamba instead of conda for better build performance \ No newline at end of file diff --git a/CHANGES.md b/CHANGES.md index 10deba2..88bb2bf 100644 --- a/CHANGES.md +++ b/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. diff --git a/README.md b/README.md index e8baad0..49244f0 100644 --- a/README.md +++ b/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 -``` - - - -[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 +``` \ No newline at end of file diff --git a/bw_graph_tools/graph_traversal.py b/bw_graph_tools/graph_traversal.py index bc6f04b..9cb3537 100644 --- a/bw_graph_tools/graph_traversal.py +++ b/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 ------- diff --git a/docs/conf.py b/docs/conf.py index 7413ef6..c16e534 100644 --- a/docs/conf.py +++ b/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,10 +19,16 @@ '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'] @@ -38,6 +36,27 @@ # 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 = [ diff --git a/docs/pages/changelog.md b/docs/content/changelog.md similarity index 100% rename from docs/pages/changelog.md rename to docs/content/changelog.md diff --git a/docs/pages/codeofconduct.md b/docs/content/codeofconduct.md similarity index 100% rename from docs/pages/codeofconduct.md rename to docs/content/codeofconduct.md diff --git a/docs/pages/contributing.md b/docs/content/contributing.md similarity index 100% rename from docs/pages/contributing.md rename to docs/content/contributing.md diff --git a/docs/pages/license.md b/docs/content/license.md similarity index 100% rename from docs/pages/license.md rename to docs/content/license.md diff --git a/docs/content/usage.md b/docs/content/usage.md new file mode 100644 index 0000000..b0e7a7e --- /dev/null +++ b/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) diff --git a/docs/environment.yaml b/docs/environment.yaml new file mode 100644 index 0000000..51d27bc --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/environment.yml b/docs/environment.yml deleted file mode 100644 index d3b014f..0000000 --- a/docs/environment.yml +++ /dev/null @@ -1,15 +0,0 @@ -name: sphinx_furo -channels: - - conda-forge - - nodefaults -dependencies: - # core functionality - - python=3.11 - - ipython - # sphinx - - sphinx=5.3.0 # sphinx-design currently requires sphinx[version>=2,<5] - - furo=2023.3.27 # website theme - - myst-parser=0.19.1 # Markdown support - - sphinx-autobuild=2021.3.14 # live-html support - - sphinx-autoapi=2.1.0 # to build docs from source code instead of package import - - sphinx-click==4.1.0 # to build docs from click command line interface \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index c25a708..65adda7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,22 @@ -```{include} ../README.md ---- -end-before: ---- -``` +# 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/contributing -Code of Conduct -License -Changelog -``` +self +content/usage +content/api +content/changelog +content/contributing +content/codeofconduct +content/license +``` \ No newline at end of file diff --git a/docs/pages/usage.md b/docs/pages/usage.md deleted file mode 100644 index 3b8614c..0000000 --- a/docs/pages/usage.md +++ /dev/null @@ -1,7 +0,0 @@ -# Usage - -```{eval-rst} -.. click:: bw_graph_tools.cli:run - :prog: bw_graph_tools - :nested: full -```