Merge pull request #59 from brightway-lca/notebooks_upgrade

Notebooks upgrade

.readthedocs.yml

@@ -1,9 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: "ubuntu-lts-latest"
   tools:
-    python: "mambaforge-22.9" # 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
   jobs:
     pre_build:
       # Generate the Sphinx configuration for this Jupyter Book so it builds.

CHANGES.md

@@ -0,0 +1,12 @@
+# `brightway-book` Changelog
+
+## `1.0.0` (2024-10-25)
+
+First fully tested release of the "Learn Brightway" book. This release was prepared as part of the Documentation Hackathon at [Brightcon 2024](https://2024.brightcon.link).
+
+The book now includes:
+
+- a long section on Brightway2 by @KarinTreyer
+- a long section on Brightway25 by @alyabolowich based on ealier work of @maximikos
+
+All sections were edited for publication by @michaelweinold, @mariashoeller and @mehdiiguider.

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright © 2023, Brightway Developers
+Copyright © 2024, Brightway Developers
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

_config.yml

@@ -3,8 +3,8 @@
 
 #######################################################################################
 # book settings
-title: Brightway Learn
-author: Brightway Contributors
+title: Learn Brightway
+author: Brightway Contributors © 2024
 logo: auxiliary/logo.png
 only_build_toc_files: true
 
@@ -21,7 +21,15 @@ execute:
 html:
   favicon: auxiliary/favicon.png
   use_repository_button: true
-  announcement: "⚠️ Brightway Learn is in Public Beta ⚠️"
+  # https://jupyterbook.org/en/stable/advanced/html.html#adding-a-license-to-your-html-footer
+  extra_footer: |
+    <p>
+    All content is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>
+    </p>
+
+sphinx:
+  config:
+    html_show_copyright: false
 
 #######################################################################################
 # LaTeX-specific settings
@@ -34,10 +42,10 @@ latex:
 # https://jupyterbook.org/en/stable/interactive/launchbuttons.html#launchbuttons-binder
 # https://jupyterbook.org/en/stable/interactive/thebe.html
 
-launch_buttons:
-  notebook_interface: "classic"
-  binderhub_url: "https://mybinder.org"
-  thebe: false
+#launch_buttons:
+#  notebook_interface: "classic"
+#  binderhub_url: "https://mybinder.org"
+#  thebe: false
 
 repository:
   url: https://github.com/brightway-lca/brightway-learn
@@ -47,7 +55,8 @@ repository:
 # bibliography settings
 
 bibtex_bibfiles:
-  - bibliography/references.bib
+  - content/bibliography/references.bib
 sphinx:
   config:
-    bibtex_reference_style: author_year
+    bibtex_reference_style: author_year
+    html_show_copyright: false

_toc.yml

@@ -4,11 +4,19 @@
 format: jb-book
 root: content/home
 parts:
-  - caption: Getting Started
+  - caption: Brightway2
     chapters:
-      - file: content/notebooks/BW2_for_beginners.ipynb
-      - file: content/notebooks/BW25_for_beginners.ipynb
-  - caption: Contributing
+      - file: content/chapters/BW2/BW2_introduction.ipynb
+  - caption: Brightway25
     chapters:
-      - file: content/markdown/contributing.md
-      - file: content/markdown/errors.md
+      - file: content/chapters/BW25/BW25_introduction.ipynb
+  - caption: Further Reading
+    chapters:
+      - file: content/auxiliary/materials.md
+  - caption: Improving the Book
+    chapters:
+      - file: content/auxiliary/contributing.md
+      - file: content/auxiliary/errors.md
+  - caption: Recent Updates to the Book
+    chapters:
+      - file: content/auxiliary/changelog.md

content/notebooks/BW25_for_beginners.ipynb → archive/archive_bw25_introduction.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# BW25 for Beginners"
+    "# Brightway25 (\"BW25\")"
    ]
   },
   {

content/notebooks/BW2_for_beginners.ipynb → archive/archive_bw2_setup.ipynb

@@ -6,7 +6,7 @@
     "id": "Fq8XglwaC6Wh"
    },
    "source": [
-    "# Brightway2 for Beginners"
+    "# Setup"
    ]
   },
   {
@@ -15,14 +15,7 @@
    "source": [
     "```{admonition} Authors\n",
     ":class: hint\n",
-    "This page was created by [Karin Treyer](https://www.psi.ch/en/ta/people/karin-treyer), [Anish Koyamparambath](https://www.linkedin.com/in/anishkoyamparambath/) and [Michael Weinold](https://www.linkedin.com/in/michaelweinold/) in September 2023 as part of the [BrightCon 2023 hackathon](https://web.archive.org/web/20230918043912/https://2023.brightcon.link/).\n",
-    "```\n",
-    "\n",
-    "```{admonition} License\n",
-    ":class: seealso\n",
-    "This page is licensed under a [Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). \\\n",
-    "You can give credit or cite this page as: \\\n",
-    "`Chapter \"Brightway2 for Beginners\" from the \"Learn Brightway\" Online Book (https://learn.brightway.dev/) by Brightway Contributors (2023)`\n",
+    "This page was originally created by [Karin Treyer](https://www.psi.ch/en/ta/people/karin-treyer), [Anish Koyamparambath](https://www.linkedin.com/in/anishkoyamparambath/) and [Michael Weinold](https://www.linkedin.com/in/michaelweinold/) in September 2023 as part of the [BrightCon 2023 hackathon](https://web.archive.org/web/20230918043912/https://2023.brightcon.link/).\n",
     "```\n",
     "\n",
     "```{note}\n",
@@ -41,7 +34,9 @@
     "id": "9fpIeP1UDSCa"
    },
    "source": [
-    "## Installing Anaconda"
+    "## Python Environment\n",
+    "\n",
+    "### Anaconda"
    ]
   },
   {
@@ -59,13 +54,25 @@
     "Both Anaconda and Miniconda can be used to download Brightway into your computer."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Environments\n",
+    "\n",
+    "Environments are a core concept of Conda. An environment is essentially a directory that contains a specific collection of Conda packages that you have installed. You can have multiple environments on your computer, each with different versions of packages. This allows you to work on different projects with different package requirements without them interfering with each other.\n",
+    "\n",
+    "You can also specify the **version number of the package**, e.g. ***\"python =3.10\"***. This is sometimes useful, when packages are not yet aligned well in terms of versions, i.e. bw is not yet adapted to use the very latest version of python. You can add as many packages as you want to the conda create command. See [below](#Maintaining-an-environment) for an explanation how conda knows where to fetch the packages.  \n",
+    "In practice, you should set up an environment for each LCA project you are working on. So, to start a project, apply the code line above, but give it an own environment name. Like this you create a project-specific environment and download the brightway2 package (=install BW2 in this env)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
     "id": "QajKB9vyDfaj"
    },
    "source": [
-    "## Using Conda to download the brightway2 package"
+    "## Using Conda to download the `brightway2` Package"
    ]
   },
   {
@@ -74,64 +81,72 @@
     "id": "JfIcrN3IDkIG"
    },
    "source": [
-    "There are different versions of Brightway (1, 2 & 2.5) and the differences between them are explained in this [page](https://docs.brightway.dev/en/latest/content/faq/brightway.html).\n",
-    "\n",
-    "This notebook will demonstrate the use of **Brightway version 2**, which is compatible with Activity Browser (v2.5 is currently not).\n",
-    "\n",
-    "A documentation explaining how to [install brightway](https://docs.brightway.dev/en/legacy/content/installation/installation.html) is available in the documentation which is the same as explained below.\n",
+    "There are different versions of Brightway (1, 2 & 2.5). The differences between these are explained [on the Brightway Documentation page](https://docs.brightway.dev/en/latest/content/faq/brightway.html).\n",
     "\n",
-    "Once you install Anaconda or Miniconda, you can access the Anaconda Navigator **(See option 1**, *only if you download the Anaconda distribution*) or you can access the Anaconda prompt **(See option 2**, *available in both Anaconda & Miniconda distribution).*\n",
+    "```{admonition} Warning\n",
+    ":class: warning\n",
+    "This notebook will demonstrate the use of **Brightway version 2** (`brightway2`)!\n",
+    "```\n",
     "\n",
-    "**Option 1:** **Anaconda Navigator** is a Graphical User Interface to download the required packages. It is recommended to *create an environment* where you will install brightway. An environment allows you to have different versions of installed packages. For instance, brightway 2 requires a specific version of background libraries that are necessary to run brightway smoothly.\n",
+    "### Option 1: Anaconda Navigator\n",
     "\n",
-    "If you install all your projects in the same environment, you might run into issues. Creating an environment avoids such issues. More information on how to handle environments are explained below.\n",
+    "The Anaconda Navigator is a graphical user interface, which allows you to download Conda packages. Packages can be collected into _environments_. This allows you to ensure you always have the right versions of different packages collected in one place.\n",
     "\n",
-    "To create environment, click on the **Environments** tab in the left and below you will find an option called **Create** which will create a new environment with your desired name.\n",
+    "The Anaconda Navigator documentation provides information on how to [create and manage environments](https://docs.anaconda.com/navigator/tutorials/manage-environments/) and [install packages into these environments](https://docs.anaconda.com/navigator/tutorials/manage-packages/#installing-a-package).\n",
     "\n",
-    "**Note: An environment name cannot be repeated.**\n",
+    "```{admonition} Warning\n",
+    ":class: warning\n",
+    "Environment names must be unique!\n",
+    "```\n",
     "\n",
-    "Once you create an environment, on the *top right corner* in the search bar search for *brightway2* and install (all the necessary libraries are automatically installed).\n",
+    "1. [Create an environment in Anaconda Navigator.](https://docs.anaconda.com/navigator/tutorials/manage-environments/#creating-a-new-environment)\n",
+    "2. [Install `brightway2` into this environment.](https://docs.anaconda.com/navigator/tutorials/manage-packages/#installing-a-package)\n",
+    "3. From the __Home__ tab of the Anaconda Navigator, launch Jupyterlab (or Jupter notebook)\n",
     "\n",
-    "To run jupyter notebook, click on **Home** from the top left corner of the navigator (Ensure the correnct environment is selected i.e *bw*) and then click on **Launch** under Jupyterlab or Jupter notebook.\n",
+    "**Note: The notebook launches in the default directory i.e., the home directory. Changing it is complicated that to use Anaconda prompt to install jupyter which is explained below.**\n",
     "\n",
-    "To deactivate an environment after work, simply click on the base or another environment from the Anaconda Navigator.\n",
+    "### Option 2: Anaconda Prompt\n",
     "\n",
-    "**Note: The notebook launches in the default directory i.e., the home directory. Changing it is complicated that to use Anaconda prompt to install jupyter which is explained below.**\n",
+    "The Anaconda Prompt is a console environment that is available in _both_ Anaconda and Miniconda distributions. This means that once you have installed Anaconda or Miniconda, you will find the prompt in your computer menu or when searching your computer for `anaconda prompt`. It allows you to do everything the Anaconda Navigator can do... just from the console, without a graphical user interface.\n",
     "\n",
-    "**Option 2:** **Anaconda prompt** is a console environment that is available in both Anaconda and Miniconda distributions. This means when you have installed Anaconda or Miniconda, you will find the prompt in your computer menu or when searching your computer for \"anaconda prompt\". Once you have located it, open it.  Copy the following code into the anaconda prompt.\n",
+    "1. Open the Anaconda Prompt.\n",
+    "2. Create a new environment called `bw` and install the `brightway2` package using the following prompt command:\n",
     "\n",
     "```bash\n",
     "conda create -n bw -c conda-forge brightway2 jupyterlab\n",
     "```\n",
     "\n",
-    "\n",
-    "(--> see further below in Chapter \"Setting up an environment\" for more details!) This code creates an environment named *'bw'* that can be changed and it also installs *jupyterlab* that allows to use a web based interface to execute python code.\n",
-    "\n",
-    "In order to use brightway, you must activate the environment using the following code:\n",
+    "Here, we have also installed `jupyterlab`, which allows to use a web based interface to execute python code. In order to use brightway, you must activate this newly created environment using the following code:\n",
     "\n",
     "```bash\n",
     "conda activate bw\n",
     "```\n",
     "\n",
-    "Note: If you are using another editor or an Integrated Development Environment (IDE) such as pycharm, VSCode, spyder or others remember to select/setup the appropriate environment before executing the code.\n",
+    "```{admonition} Warning\n",
+    ":class: warning\n",
+    "If you are using another editor or an Integrated Development Environment (IDE) such as pycharm, VSCode, Spyder, etc. please remember to select/setup the appropriate environment before executing the code.\n",
+    "```\n",
     "\n",
-    "To use jupter notebook such as this file, after activating the environment run the following code:\n",
+    "You can now launch Jupyterlab (or Jupyter notebook) from the Anaconda prompt by typing:\n",
     "\n",
     "```bash\n",
     "jupyter notebook\n",
     "```\n",
     "\n",
-    "Note: Remember to navigate to the desired folder before executing the above code as it is complicated to go out of the folder to save your notebook after it starts.\n",
+    "Remember to navigate to the desired folder before executing the above code as it is complicated to go out of the folder to save your notebook after it starts.\n",
     "\n",
     "To deactivate the environment after working on your project use the following code:\n",
     "\n",
     "```bash\n",
     "conda deactivate\n",
     "```\n",
     "\n",
-    "Note: In order to deactivate, you must first save and close the jupyter notebook. Save your work before quitting. Go to the home page of the notebook (the page that shows you the directory and different files and click on `quit`.\n",
+    "In order to deactivate, you must first save and close the jupyter notebook. Save your work before quitting. Go to the home page of the notebook (the page that shows you the directory and different files and click on `quit`.\n",
     "\n",
-    "Imp Note: Clicking on `logout` will not quit the jupyter notebook and you cannot provide an input into the terminal. In such cases, press `CTR+C`(Windows & Mac) to quit jupyter notebook which allows you to then deactivate the environment.\n",
+    "```{admonition} Warning\n",
+    ":class: warning\n",
+    "Clicking on `logout` will not quit the jupyter notebook and you cannot provide an input into the terminal. In such cases, press `CTR+C`(Windows & Mac) to quit jupyter notebook which allows you to then deactivate the environment.\n",
+    "```\n",
     "\n",
     "After working with brightway, remember to deactivate the environment either using Anaconda Navigator or Anaconda prompt."
    ]
@@ -142,7 +157,7 @@
     "id": "qZPZt28sC6Wl"
    },
    "source": [
-    "## Working with environments"
+    "## Working with Environments"
    ]
   },
   {
@@ -151,21 +166,10 @@
     "id": "5juW4JYhC6Wn"
    },
    "source": [
-    "### Setting up an environment"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "LRK1G8Y7C6Wn"
-   },
-   "source": [
+    "### What are Environments?\n",
     "\n",
-    "You will work with environments in conda, see the official [conda page](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html).\n",
     "\n",
-    "**\"A conda environment is a directory that contains a specific collection of conda packages that you have installed.\"** When you install Brightway, they will be installed in a specific environment which will contain all necessary packages. You can e.g. have one environment for brightway2, and one for brightway25.\n",
     "\n",
-    "When you will install e.g. Brightway2, you will execute this line:\n",
     "\n",
     "```bash\n",
     "conda create -n bw brightway2 jupyterlab\n",
@@ -280,38 +284,6 @@
     "\n"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "5eTohz02C6Wp"
-   },
-   "source": [
-    "## Recap: Installing brightway2 on your computer"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "R_5Q7E0mC6Wq"
-   },
-   "source": [
-    "You may already have installed bw2 and ab while reading above.\n",
-    "\n",
-    "In case not, or in case you want this to be summarised, here's how to get these two packages on your computer:"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "id": "mxlmIjvrC6Wq"
-   },
-   "source": [
-    "[Brightway2](#Using-Conda-to-download-the-brightway2-package): Follow the setup instruction from bw2 [here](https://docs.brightway.dev/en/legacy/content/setup/setup.html).\n",
-    "\n",
-    "Namely: ```conda create -n bw brightway2 jupyterlab``` creates the environment AND fetches the two packages brightway2 and jupyterlab from the channel conda-forge.\n",
-    "And with ```conda activate bw```, you access the environment so that you can make use of all the packages which are included in it, such as LCA calculations, handling of LCA databases, etc.\n"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {

content/auxiliary/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../../CHANGES.md
+```