Getting started, installation rewrite

source/installation/access-countrys-source-code.md

@@ -0,0 +1,21 @@
+# Access a country's source code
+
+This section provides instructions to run or modify the [source code](https://github.com/openfisca/country-template) of the `OpenFisca-Country-Template` package.
+
+These instructions should be able to be followed for any OpenFisca country package, just substitute the `OpenFisca-Country-Template` package with the relevant OpenFisca country package.
+
+OpenFisca runs with [Python](https://www.python.org/). Its source code is managed with the [Git](https://git-scm.com) version control software. The following steps call the [pip package installer](https://pypi.org/project/pip/) which requires a `Python` installation and a `git` command. To check their installation or install them, follow the [Installation requirements](installation-requirements.md) section.
+
+The `OpenFisca-Country-Template` installation instructions are in its `README` [Advanced installation](https://github.com/openfisca/country-template#b-advanced-installation-git-clone) section.
+
+> 💡 Other OpenFisca models have their own documentation. Check the existing repositories list on the [Available Packages](https://openfisca.org/en/packages/) section of the openfisca.org website.
+
+## Testing changes on "ready to use" situations
+
+Generally when making changes to legislation, there is a need to test the changes with a situation that works with the country's tax and benefit system.
+
+Sometimes, these situations can be quite complicated to model. Instead of rewriting them everytime, they can be packaged in different formats:
+
+* As [YAML tests](./../coding-the-legislation/writing_yaml_tests.md) when the output result should be registered.
+* As [JSON requests](./../openfisca-web-api/input-output-data.md#describing-the-situation) when the output isn't being tested. Refer to [these examples](https://github.com/openfisca/country-template/tree/main/openfisca_country_template/situation_examples) in the `OpenFisca-Country-Template` repository. These can be adapted as requests to be sent to the OpenFisca web API.
+* As [CSV or other data formats](./../simulate/run-simulation.md#data) when there is a large number of situations to save.

source/installation/call-existing-web-api.md

@@ -0,0 +1,13 @@
+# Call an existing web API
+
+There is a demonstration of the `OpenFisca-Country-Template` web API hosted by OpenFisca community. It is available for testing and interacting with its web API endpoints through [this swagger interface](https://legislation.demo.openfisca.org/swagger). As with all OpenFisca country web API's it does not require installing anything to access it.
+
+For further information on the possible requests, [this section of the documentation](./../openfisca-web-api/endpoints.md) describes OpenFisca web APIs endpoints.
+
+> 💡 Other OpenFisca models might have their own hosted web APIs. When looking for an already hosted web API of a specific country package, it is recommended to check the terms of use and contact the maintaining team.
+
+The `OpenFisca-Country-Template` demonstration API provides examples of the endpoints that are available with all OpenFisca packages. To develop an application that requires calculations specific to a country, that country's OpenFisca web API will be required to access the variables and calculations specific to that country.
+
+It is advised to host specific OpenFisca instances per application as changes to laws can often require application changes. This will give maintainers the ability to migrate the application to the latest version of a country package in their own timeframes.
+
+Read [Install a country web API](./install-country-web-api.md) for more information.

source/installation/index.md

@@ -1,34 +1,59 @@
-# <i class="fas fa-cogs"></i> Get started
+# <i icon-name="download"></i> Getting started
 
 ```eval_rst
 .. toctree::
    :hidden:
 
-   presets
-   call-hosted-web-api
-   run-web-no-local-install
-   install-wheel
-   install-openfisca-country-template
-   install-openfisca-web-api
-   install-with-docker
-   windows-no-admin
-   offline-environment
+call-existing-web-api
+installation-requirements
+install-country-web-api
+install-country-package
+python-api-browser
+access-countrys-source-code
+install-with-docker
+offline-environment
+windows-no-admin
 ```
 
-This section guides you in installing the [`OpenFisca-Country-Template`](https://github.com/openfisca/country-template) country package as a generic example of an OpenFisca country package. This will also allow you to run the documentation examples on your local environment.
+This section is a guide to the various methods of accessing or installing OpenFisca. Follow the guide below to establish what the use case is and get directed to the appropriate section(s).
 
-This model is fictitious and for your project, you will obviously want to work with one that models the set of rules of an actual jurisdiction. We advise you to refer to your target country package repository documentation for specific instructions. Nevertheless, the steps for installing should be similar for every package. 
+## 1) Identify the country package
 
-If you are working on a web application or would like to test the web API online:
-* No installation is needed if you [call a public instance](./call-hosted-web-api.md) of the web API.
-* [Install the country package web API](./install-openfisca-web-api.md) to operate your own web API instance with no usage limitations or to send requests with private data, .
+The most common approach involves a specific country or jurisdiction package and so in this scenario it's important to identify if that package exists and then continue to step 2 _"Clarify use case"_.
+If the goal is contributing to OpenFisca directly (such as this documentation); have a look at the [Contribute](/contribute/index.md) section of this site and also the [OpenFisca Github repositories](https://github.com/openfisca/).
 
-If you want to use an OpenFisca country package without editing the model rules:
-* The fastest is to [load the country package on a web hosted Python runtime](./run-web-no-local-install.md).
-* To call calculations from your machine, you can [install the country package on your local environment](./install-wheel.md).
+## 2) Clarify use case
 
-If you want to both, use and contribute to the rules of a country package, [install it in editable mode](./install-openfisca-country-template.md).
+With a specific country or jurisdiction package in mind; ask whether the use case requires [contributions to the rules](index.md#contributing-to-the-rules), or intends to just [utilise existing rules](index.md#utilising-existing-rules) (for example: run simulations).
 
-Finally, some edge cases has been identified by the OpenFisca community. Here is some additional documentation to help you:
-* If you need to [install OpenFisca on a Windows machine without administrative rights](./windows-no-admin.md).
-* If you need to [install OpenFisca on a server without internet access](./offline-environment.md).
+### Utilising existing rules
+
+If the goal is just to utilise existing rules (rather than contributing to the rules) then consider the following options.
+
+#### Web API
+
+Best for online web applications. The two options are:
+
+* If it exists, [call an existing web API](./call-existing-web-api.md) for your country (no installation necessarily), or
+* [Install a country web API](./install-country-web-api.md) to operate your own web API with no usage limitations (see also [Install with Docker](./install-with-docker.md)).
+
+#### Python API
+
+Suitable for "desktop" processing and running large simulations:
+
+* [Install a country package](./install-country-package.md) in a local environment (see also [Install with Docker](./install-with-docker.md)).
+* Alternatively, access the [Python API in the browser](./python-api-browser.md).
+
+### Contributing to the rules
+
+If the goal includes contributing to the rules of a country package:
+
+* when it already exists, [access a country's source code](./access-countrys-source-code.md).
+* otherwise [bootstrap a new country package](/coding-the-legislation/bootstrapping_a_new_country_package.md)
+
+## Edge cases
+
+Finally, some specific edge cases have been described by the OpenFisca community as follows:
+
+* Installing a specific country OpenFisca package in an [offline environment](./offline-environment.md).
+* Installing a specific country OpenFisca package on a [Windows machine without administrative rights](./windows-no-admin.md).

source/installation/install-country-package.md

@@ -0,0 +1,27 @@
+# Install a country package
+
+This section is a guide on how to install the `OpenFisca-Country-Template` [packaged library](https://pypi.org/project/OpenFisca-Country-Template/).
+
+These instructions should be able to be followed for any OpenFisca country package that has published their package on [https://pypi.org/](https://pypi.org/)
+
+It's the minimal installation required to run a country package without the intention of contributing to it. If the use case also requires contributing to the model, please follow the [access a country's source code](./access-countrys-source-code.md) section.
+
+## Install OpenFisca-Country-Template packaged library
+
+OpenFisca runs with [Python](https://www.python.org/). The following steps call [pip package installer](https://pypi.org/project/pip/) which requires a `Python` installation. To check its installation or install it, first check the [Installation requirements](installation-requirements.md).
+
+> When other Python projects exist in the intended environment, it is recommended to create a new virtual environment to avoid dependency conflicts. [Here is more information](https://github.com/openfisca/country-template#setting-up-a-virtual-environment-with-venv) from `OpenFisca-Country-Template` documentation.
+
+To install the latest OpenFisca-Country-Template [published revision](https://pypi.org/project/OpenFisca-Country-Template/#history), run the following command in the environment's terminal:
+
+```shell
+pip install OpenFisca-Country-Template
+```
+
+It should complete without any errors. To check the installed packages run the following command:
+
+```shell
+pip list
+```
+
+`OpenFisca-Country-Template` should be in the list indicating that it is installed and ready to run simulations.

source/installation/install-country-web-api.md

@@ -0,0 +1,13 @@
+# Install a country web API
+
+These instructions are for installing an OpenFisca country package in a local environment. The `OpenFisca-Country-Template` package is used as an example here and should be substituted for the specific country package relevant to the use case.
+
+## Run and call a local web API
+
+OpenFisca runs with [Python](https://www.python.org/). If it's not installed in the environment, check the [Installation requirements](installation-requirements.md#install-python) section.
+
+To run a local `OpenFisca-Country-Template` web API:
+
+1. Install the `OpenFisca-Country-Template` in the local environment as described by it's `README` [Install Instructions for Users and Contributors](https://github.com/openfisca/country-template#install-instructions-for-users-and-contributors) section,
+
+2. Serve the web API on your environment by running the one command described [here](https://github.com/openfisca/country-template#serve-this-country-package-with-the-openfisca-web-api).