LCA-ActivityBrowser · mrvisscher · Sep 18, 2024 · Aug 30, 2024 · Aug 30, 2024 · Aug 30, 2024
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,23 +1,28 @@
 <!--
-Thank you for your pull request. Please provide a description above and
-review the checklist below.
+Thank you for your pull request. 
+Please provide a description above and review the checklist below.
 
 Contributors guide: ./CONTRIBUTING.md
 -->
 
 ## Checklist
 <!--
-Remove items that do not apply. For completed items, change [ ] to [x] or you can click the checkboxes once your 
-pull-request is published.
+Remove items that do not apply. 
+For completed items, change [ ] to [x] or you can click the checkboxes once your pull-request is published.
 -->
 
 - [ ] Keep pull requests small so they can be easily reviewed.
-- [ ] Update the documentation, please follow the [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
+- [ ] Update the documentation
+  - For in-code documentation, please follow the [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
+  - For user documentation, please update the wiki in 
+    [`./activity_browser/docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki)
 - [ ] Update tests.
+- [ ] Link this PR to related issues by using [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+
+#### If you have write access (otherwise a maintainer will do this for you):
 - [ ] Categorize the PR by setting a good title and adding one of the labels:
       `bug`, `feature`, `ui`, `change`, `documentation`, `breaking`, `ci`
       as they show up in the changelog.
-- [ ] Link this PR to related issues by using [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
 - [ ] Add a milestone to the PR (and related issues, if any) for the intended release.
 - [ ] Request a review from another developer.
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -42,8 +42,9 @@ If you want to contribute to the wiki, either by adding figures or links or by w
 new sections, please [contact the developers](https://github.com/LCA-ActivityBrowser/activity-browser#developers)! 
 
 #### Making changes to the wiki _(for developers)_
-Any images or other assets in the documentation should be stored in `docs/assets` and linked to there instead of 
-online links (unless copyrighted material is linked that cannot be shown in any other way).
+Any images or other assets in the documentation should be stored in `docs/wiki/assets` and linked to there instead of 
+online links (unless copyrighted material is linked that cannot be shown in any other way). 
+This way all assets are stored in the wiki git.
 
 To make changes to the wiki, open a pull request with suggested changes to 
 [`docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki).
@@ -214,9 +215,12 @@ When the tests pass on a pull-request, one of the maintainers of AB will review
 
 ### Do's and Don'ts
 - Please do document any new code you wish to include in the activity browser.
-  This means writing useful documentation in the code (please follow the 
-  [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)), but also writing useful tooltips, labels
-  and other things that can help users.
+  This means:
+  - Writing useful documentation in the code (please follow the 
+  [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)), 
+  - Writing useful tooltips, labels and other things that can help users in the software,
+  - Updating the wiki in 
+    [`./activity_browser/docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki)
 - Where possible, avoid importing and using brightway2 classes and methods directly in the Qt application code. 
   If some complex data processing is needed, see if your use-case is covered by bwutils instead. 
   If bwutils does not contain any for your use-case you are welcome to add it.

diff --git a/README.md b/README.md
@@ -13,189 +13,43 @@
 
 The **Activity Browser (AB) is an open source software for Life Cycle Assessment (LCA)** that builds on [Brightway2](https://brightway.dev).
 
-[Video tutorials](https://www.youtube.com/channel/UCsyySKrzEMsRFsWW1Oz-6aA/) are available on youtube.
-
-Please also read and cite our [scientific paper](https://doi.org/10.1016/j.simpa.2019.100012).
-
-
 ### Some highlights
 
 - **Fast LCA calculations**: for multiple reference flows, impact categories, and scenarios
 - **A productivity tool for brightway**: model in brightway (python) and see the results in the AB or vice-versa
 - **Advanced modeling:** Use parameters, scenarios (including prospective LCI databases from [premise](https://premise.readthedocs.io/en/latest/)), uncertainties and our Graph Explorer
 - **Advanced analyses:** Contribution analyses, Sankey Diagrams, Monte Carlo, and Global Sensitivity Analysis
+- **Plugins:** Extend the functionality of Activity Browser with 
+[Plugins](https://github.com/LCA-ActivityBrowser/activity-browser/wiki/Plugins)
 
 # Contents
 - [Installation](#installation)
-- [Updating the AB](#updating-the-ab)
-- [Getting started](#getting-started)
-    - [Running the AB](#running-the-ab)
-    - [Importing LCI databases](#importing-lci-databases)
-    - [Additional Resources](#additional-resources)
-- [Plugins](#plugins)
-    - [Available plugins](#available-plugins)
-    - [Installation](#installation-1)
-    - [Usage](#usage)
-    - [Development](#development)
+- [First Steps](#first-steps)
 - [Contributing](#contributing)
 - [Developers](#developers)
 - [Copyright](#copyright)
 - [License](#license)
 
 # Installation
 
-## The quick way
-
-You can install and start the activity-browser like this:
-
-```bash
-conda create -n ab -c conda-forge --solver libmamba activity-browser
-conda activate ab
-activity-browser
-```
-
-### Mamba
-
-You can also install the AB using [Mamba](https://mamba.readthedocs.io/en/latest/mamba-installation.html#mamba-install):
-
-```bash
-mamba create -n ab activity-browser
-mamba activate ab
-activity-browser
-```
-
-## The thorough way
-### Conda
-
-We recommend that you use **conda** to manage your python installation. You can install [Anaconda](https://www.anaconda.com/products/individual) or the more compact [miniconda](https://conda.io/miniconda.html) (Python 3 version) for your operating system. Installation instructions for miniconda can be found [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html). See also the [conda user guide](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html) or the [Conda cheat sheet](https://docs.conda.io/projects/conda/en/latest/_downloads/843d9e0198f2a193a3484886fa28163c/conda-cheatsheet.pdf).
-
-Skip this step if you already have a working installation of anaconda or miniconda, but make sure to keep your conda installation up-to-date: `conda update -n base conda`.
+## Step-by-step guide
+See our 
+[Installation Guide](https://github.com/LCA-ActivityBrowser/activity-browser/wiki/Installation-Guide) 
+wiki page for a step-by-step guide to installing Activity Browser.
 
-### Add the Conda-Forge channel
-The activity-browser has many dependencies that are managed by the [conda-forge](https://conda.io/docs/user-guide/tasks/manage-channels.html) channel. Open a cmd-window or terminal (in Windows you may have to use the Anaconda prompt) and type the following:
-
-```bash
-conda config --prepend channels conda-forge
-```
-Also configure conda to use the libmamba solver which is significantly faster than the default.
-```bash
-conda config --set solver libmamba
-```
-
-### Installing Activity Browser
+## The quick way
+Or you can install and start the activity-browser like this:
 
 ```bash
 conda create -n ab -c conda-forge activity-browser
 conda activate ab
 activity-browser
 ```
 
-#### Activity Browser is installed
-
-At this point the activity-browser and all of its dependencies will be installed in a new conda environment called `ab`. You can change the environment name `ab` to whatever suits you.
-
-## Updating the AB
-
-We recommend to regularly update the AB to receive new features & bugfixes. These commands will update the activity-browser and all of its dependencies in the conda environment called `ab`.
-
-```bash
-conda activate ab
-conda update activity-browser
-```
-
-# Getting started
-
-## Running the AB
-
-First activate the environment where the activity browser is installed:
-
-```bash
-conda activate ab
-```
-
-Then simply run `activity-browser` and the application will open.
-
-## Importing LCI databases
-
-- In the `Project`-tab there is initially a button called _"Add default data (biosphere flows and impact categories)"_. Click this button to add the default data. This is equivalent to `brightway2.bw2setup()` in python.
-- After adding the default data, you can import a database with the _"Import Database"_-Button. Follow the instructions of the database import wizard. Imports can be done in several ways:
-    - Directly from the ecoinvent homepage (ecoinvent login credentials required)
-    - From a 7zip archive
-    - From a directory with ecospold2 files (same as in brightway2)
-    - From Excel files using the brightway Excel format
-
-## Additional Resources
-
-- [Youtube tutorials](https://www.youtube.com/channel/UCsyySKrzEMsRFsWW1Oz-6aA/)
-- [Introduction video by ETH Zurich](https://www.youtube.com/watch?v=j3uLptvsxeA)
-- [AB Discussions page](https://github.com/LCA-ActivityBrowser/activity-browser/discussions)
-- [AB Wiki](https://github.com/LCA-ActivityBrowser/activity-browser/wiki)
-- [AB scientific article](https://doi.org/10.1016/j.simpa.2019.100012)
-- The AB has two mailing lists, for [updates](https://brightway.groups.io/g/AB-updates) and [user exchange](https://brightway.groups.io/g/AB-discussion)
-- [Brightway2](https://brightway.dev/)
-- [Global Sensitiviy Analysis paper](https://onlinelibrary.wiley.com/doi/10.1111/jiec.13194) describing GSA as implemented in the AB; see also our [wiki](https://github.com/LCA-ActivityBrowser/activity-browser/wiki/Global-Sensitivity-Analysis)
-- [Modular LCA paper](https://link.springer.com/article/10.1007/s11367-015-1015-3); [documentation modular LCA](http://activity-browser.readthedocs.io/en/latest/index.html); re-implementation of modular LCA into the AB is [ongoing](https://github.com/marc-vdm/activity-browser/tree/mLCA)
-
-# Plugins
-| :warning: DISCLAIMER                                                                                                                                                                  |
-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Plugins are not necessarily developed by Activity Browser maintainers. Below are listed plugins from people we trust but we do not check plugins code. **Use them at your own risk**. |
-| The plugin system is still in development so keep in mind that things may change at any point.                                                                                        |
-
-Since the `2.8 release` a plugin system has been added to the AB. Plugins are a flexible way to add new functionalities to the AB without modifying the software itself.
-
-The plugin code has been designed and written by Remy le Calloch (supported by [G-SCOP laboratories](https://g-scop.grenoble-inp.fr/en/laboratory/g-scop-laboratory)) with revisions from the AB-team.
-
-
-## Available plugins
-
-These are the plugins that we know about. To add your plugin to this list either open an issue, or a pull request. All submitted plugins will be reviewed, although all risks associated with their use shall be born by the user.
-
-| Name     | Description | Links | Author(s) |
-|:---------|-------------|-------|-----------|
-| [ScenarioLink](https://github.com/polca/ScenarioLink) | Enables you to seamlessly fetch and reproduce scenario-based LCA databases, such as those generated by [premise](https://github.com/polca/premise) | [anaconda](https://anaconda.org/romainsacchi/ab-plugin-scenariolink), [pypi](https://pypi.org/project/ab-plugin-scenariolink/), [github](https://github.com/polca/ScenarioLink) | Romain Sacchi & Marc van der Meide |
-| [ReSICLED](https://github.com/Pan6ora/ab-plugin-ReSICLED) | Evaluating the recyclability of electr(on)ic product for improving product design | [anaconda](https://anaconda.org/pan6ora/ab-plugin-resicled), [github](https://github.com/Pan6ora/ab-plugin-ReSICLED) | G-SCOP Laboratory |
-| [Notebook](https://github.com/Pan6ora/ab-plugin-Notebook) | Use Jupyter notebooks from AB | [anaconda](https://anaconda.org/pan6ora/ab-plugin-template), [github](https://github.com/Pan6ora/ab-plugin-Notebook) | Rémy Le Calloch |
-| [template](https://github.com/Pan6ora/activity-browser-plugin-template) | An empty plugin to start from | [anaconda](https://anaconda.org/pan6ora/ab-plugin-template), [github](https://github.com/Pan6ora/activity-browser-plugin-template) | Rémy Le Calloch |
-
-## Installation
-
-### detailed instructions
-
-Every plugin's Github page (links are provided in the above table) should have a **Get this plugin** section with installation instructions.
-
-### general instructions
-
-Plugins are conda packages (like the Activity Browser). To add a plugin simply install it in your conda environment from the Anaconda repos.
-
-_Nb: add `-c conda-forge` to the install command like below to avoid problems with dependencies._
-
-Ex:
-
-```
-conda activate ab
-conda install -c pan6ora -c conda-forge ab-plugin-notebook
-```
-
-## Usage
-
-Once a new plugin is installed restart the Activity Browser.
-
-### enabling a plugin
-
-Plugins are enabled **per-project**. Simply open the plugin manager in the `Tools > Plugins` menu.
-
-Close the plugin manager. New tabs should have appeared in the AB (each plugin can spawn one tab on each left/right panel).
-
-### disabling a plugin
-
-Disable a plugin the same way you activated it.
-
-**:warning: Keep in mind that all data created by the plugin in a project could be erased when you disable it.**
-
-## Development
-
-The best place to start to create new plugins is the [plugin template](https://github.com/Pan6ora/activity-browser-plugin-template). Its code and README will help you to understand how to create a plugin.
+# First Steps
+See our
+[Getting Started](https://github.com/LCA-ActivityBrowser/activity-browser/wiki/Getting-Started)
+wiki page to learn how to get started using Activity Browser.
 
 # Contributing
 
@@ -213,7 +67,7 @@ If you experience problems or are suffering from a specific bug, please [raise a
 - Marin Visscher (m.r.visscher@cml.leidenuniv.nl) (main developer)
 - Marc van der Meide (m.t.van.der.meide@cml.leidenuniv.nl) (maintainer)
 
-### Important contributers
+### Important contributors
 
 - [Adrian Haas](https://github.com/haasad)
 - [Chris Mutel](https://github.com/cmutel)

diff --git a/activity_browser/docs/wiki/Activities.md b/activity_browser/docs/wiki/Activities.md
@@ -0,0 +1,5 @@
+> [!IMPORTANT]
+> This wiki section is __incomplete__ or __outdated__.
+> 
+> Please help us improve the wiki by reading our
+> [contributing guidelines](https://github.com/LCA-ActivityBrowser/activity-browser/blob/main/CONTRIBUTING.md#wiki).
diff --git a/activity_browser/docs/wiki/Databases.md b/activity_browser/docs/wiki/Databases.md
@@ -0,0 +1,5 @@
+> [!IMPORTANT]
+> This wiki section is __incomplete__ or __outdated__.
+> 
+> Please help us improve the wiki by reading our
+> [contributing guidelines](https://github.com/LCA-ActivityBrowser/activity-browser/blob/main/CONTRIBUTING.md#wiki).
diff --git a/activity_browser/docs/wiki/Flow-Scenarios.md b/activity_browser/docs/wiki/Flow-Scenarios.md
@@ -0,0 +1,5 @@
+> [!IMPORTANT]
+> This wiki section is __incomplete__ or __outdated__.
+> 
+> Please help us improve the wiki by reading our
+> [contributing guidelines](https://github.com/LCA-ActivityBrowser/activity-browser/blob/main/CONTRIBUTING.md#wiki).