Extended documentation in README.md (#47)

Better documentation and `pybamm-cookie` logo

CONTRIBUTING.md

@@ -80,10 +80,10 @@ If you performed the `pre-commit install` step above, your code changes will be
 
 All code requires testing. We use the [Pytest](https://docs.pytest.org/en/) package for our tests. (These tests typically just check that the code runs without error, and so, are more _debugging_ than _testing_ in a strict sense. Nevertheless, they are very useful to have!).
 
-If you have `nox` installed, to run tests, type
+If you have `nox` installed, to run tests for the template, type
 
 ```bash
-nox -s test-generation
+nox -s template-tests
 ```
 
 else, type
@@ -92,6 +92,11 @@ else, type
 pytest tests/
 ```
 
+To test a generated project, meaning a project generated out of `pybamm-cookie`, you can simply run
+```bash
+nox -s generated-project-tests
+```
+
 ### Writing tests
 
 Every new feature should have its own test. To create ones, have a look at the `test` directory and see if there's a test for a similar method. Copy-pasting this is a good way to start.

README.md

@@ -23,6 +23,7 @@
 [rtd-badge]:                https://readthedocs.org/projects/pybamm-cookie/badge/?version=latest
 [rtd-link]:                 https://pybamm-cookie.readthedocs.io/en/latest/?badge=latest -->
 
+![pybamm-cookie](docs/_static/pybammcookie.png)
 <!-- SPHINX-START -->
 [![Powered by NumFOCUS](https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A)](http://numfocus.org)
 [![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-red.json)](https://github.com/copier-org/copier)
@@ -63,8 +64,16 @@ Navigate into the directory you want your project directory to reside in, or use
 ```bash
 pybamm-cookie --path /path_to_copy_to
 ```
+#### Using pip/pip inside venv
+
+You can also perform a normal `pip` installation for the `pybamm-cookie` CLI and generate a project.
+```bash
+pip install pybamm-cookie
+pybamm-cookie
+```
 
 Copier will prompt you with various configurations and you may choose the ones that suit your use case.
+Additionally you can perform `pybamm-cookie -h` to know the list of actions you can perform with the CLI.
 
 **Note**: A `git` repository is automatically initialised when a project is created within a directory.
 
@@ -86,6 +95,40 @@ import pybamm_cookie
 
 pybamm_cookie.__version__
 ```
+### Project Layout
+```bash
+.
+├── .github
+│   └── workflows
+├── docs
+│   └── _static
+├── src
+│   ├── pybamm_example_project
+│   ├── models
+│   │   └── input
+│   └─ parameters
+│       └── input
+├── tests
+│    ├── generated_project_tests
+│    └── user_tests
+├─ noxfile.py
+└─ pyproject.toml
+```
+A basic generated project with `pybamm-cookie` has a directory structure like the one depicted above. Each directory has a special purpose and is highly recommended to use them for their specific purposes to avoid any errors.
+- `docs/` contains the basic configuration for building documentation using [sphinx](https://www.sphinx-doc.org/).
+- `src/` contains the main package files under a directory with your specified project name. This is where all your code should be written.
+    - `models/input/` - Contains the source code for battery models. Refer [PyBaMM models](https://docs.pybamm.org/en/latest/source/api/models/index.html) to learn how to write your own battery models.
+    - `parameters/input/` - Contains the source code for parameters sets. Refer [PyBaMM parameter sets](https://docs.pybamm.org/en/stable/source/api/parameters/parameter_sets.html) to learn more on parameter sets.
+- `tests/` The tests directory contains two sub-directories -
+    - `generated_project_tests/` - Contains pre-defined tests for verifying if the units inside generated project work well. It can be verified using `nox -s generated-project-tests` or `pytest tests/generated_project_tests` command.
+    - `user_tests/` - This directory contains all the user written tests, the example tests can be copied and modified as per your own needs. We suggest you use [pytest](https://docs.pytest.org/en/stable/) to write tests. The tests can be then run by executing `nox -s user-tests` or `pytest tests/user_tests`.
+- `noxfile.py` contains basic `nox sessions` for building documentation and runnings tests.
+- `pyproject.toml` has project metadata and build backend configurations.
+- `github/workflows/` has all the basic CI configurations to automate tests and builds on [GitHub Actions](https://github.com/features/actions).
+
+## 🚀 Motivation
+
+This project aims to enhance the usability of PyBaMM for both newcomers and experienced users alike by providing standardised templates that incorporate best practices and automation tools. The `pybamm-cookie` template is set to lower the barrier to battery modeling, making it easier for the research community to adopt PyBaMM for their battery modeling projects. The project also supports model entry points and parameter set entry points, allowing community contributors to create and share models/parameter sets of their repositories using the copier template without directly adding them upstream. This lets community contributors retain ownership and choose license terms and also grants flexibility to the PyBaMM team in supporting models. Support for all of GitHub’s functionality and infrastructure is contained within the template.
 
 ## 🛠️ Contributing to `pybamm-cookie`