Updates to docs

README.md

@@ -41,36 +41,18 @@ MapReader is a groundbreaking interdisciplinary tool that emerged from a specifi
 
 ### MapReader pipeline 
 
-The MapReader pipeline consists of two main components:
-1. preprocessing/annotation 
-2. training/inference
-
 <div align="center">
   <figure>
-  <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/MapReader_pipeline.png"
+  <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/docs/source/figures/pipeline_explained.png"
         alt="MapReader pipeline"
         width="70%">
   </figure>
 </div>
 
+The MapReader pipeline consists of a linear sequence of tasks which, together, can be used to train a computer vision (CV) classifier to recognise visual features within maps and identify patches containing these features across entire map collections.
 
-### What is included?
+See our [About MapReader](https://mapreader.readthedocs.io/en/latest/About.html) page to learn more.
 
-The MapReader package provides a set of tools to:
-
-- **download** images/maps and metadata stored on web-servers (e.g. tileserves which can be used to retrieve maps from OpenStreetMap (OSM), the National Library of Scotland (NLS), or elsewhere).
-- **load** images/maps and metadata stored locally.
-- **preprocess** images/maps:
-  - patchify (create patches from a parent image), 
-  - resample (use image transformations to alter pixel-dimensions/resolution/orientation/etc.),
-  - remove borders outside the neatline,
-  - reproject between coordinate reference systems (CRS).
-- **annotate** images/maps (or their patches) using an interactive annotation tool.
-- **train, fine-tune, and evaluate** Computer Vision (CV) models and use these to **predict** labels (i.e. model inference) on large sets of images/maps.
-
-Various **plotting and analysis** functionalities are also included (based on packages such as *matplotlib*, *cartopy*, *Google Earth*, and [kepler.gl](https://kepler.gl/)).
-
-<!--- or mb picture here? --->
 
 ## Documentation 
 
@@ -83,6 +65,24 @@ The MapReader documentation can be found [here](https://mapreader.readthedocs.io
 - Non-geospatial images 
 
  **Developers and contributors** may also want to refer to the [API documentation](https://mapreader.readthedocs.io/en/latest/api/index.html) and [Contribution guide](https://mapreader.readthedocs.io/en/latest/Contribution-guide.html) for guidance on how to contribute to the MapReader package.
+
+
+## What is included in this repo?
+
+The MapReader package provides a set of tools to:
+
+- **Download** images/maps and metadata stored on web-servers (e.g. tileserves which can be used to retrieve maps from OpenStreetMap (OSM), the National Library of Scotland (NLS), or elsewhere).
+- **Load** images/maps and metadata stored locally.
+- **Preprocess** images/maps:
+  - patchify (create patches from a parent image), 
+  - resample (use image transformations to alter pixel-dimensions/resolution/orientation/etc.),
+  - remove borders outside the neatline,
+  - reproject between coordinate reference systems (CRS).
+- **Annotate** images/maps (or their patches) using an interactive annotation tool.
+- **Train or fine-tune** Computer Vision (CV) models and use these to **predict** labels (i.e. model inference) on large sets of images/maps.
+
+Various **plotting and analysis** functionalities are also included (based on packages such as *matplotlib*, *cartopy*, *Google Earth*, and [kepler.gl](https://kepler.gl/)).
+
 
 ## How to cite MapReader
 

docs/source/Beginners-info.rst

@@ -0,0 +1,52 @@
+Coding Basics
+======================
+
+Using the terminal
+-------------------
+
+A terminal is a command-line interface where you can type in commands and interact with your computer's operating system. 
+It can be a powerful tool for programmers, allowing them to execute complex tasks with just a few keystrokes. 
+However, it can also be intimidating for beginners who are not familiar with using it. 
+
+Here are some resources to help you get started with using the terminal on your computer: 
+
+- `Introduction to the command line <https://curriculum.dhinstitutes.org/workshops/command-line/>`__
+- `Introduction to the bash command line  <https://programminghistorian.org/en/lessons/intro-to-bash>`__
+- `Introduction to the Windows command line with PowerShell <https://programminghistorian.org/en/lessons/intro-to-powershell>`__
+- `The Unix shell <https://swcarpentry.github.io/shell-novice/>`__
+- more??
+
+Python packages
+----------------
+i.e. not a program/app that you can click and find in your start page/ launch pad.
+
+- Usually no GUI
+- ??
+
+Conda and python virtual environments
+--------------------------------------
+
+A virtual environment is a way to create an isolated environment in which you can install specific versions of packages and dependencies for your Python projects. 
+This is useful because it allows you to avoid conflicts between different projects that may require different versions of the same package. 
+In the installation instructions provided, there are two methods for setting up a virtual environment for MapReader: using Anaconda (also known as conda) or using venv, which is Python's native way of handling virtual environments. 
+
+If you're new to virtual environments in Python, this tutorial provides a good introduction: 
+
+- `Getting started with python environments (using conda) <https://towardsdatascience.com/getting-started-with-python-environments-using-conda-32e9f2779307>`__
+- `Why you need python environments and how to manage them with conda <https://www.freecodecamp.org/news/why-you-need-python-environments-and-how-to-manage-them-with-conda-85f155f4353c/>`__
+- `Virtual environments and packages <https://docs.python.org/3/tutorial/venv.html>`__
+- more??
+
+Jupyter notebooks
+------------------
+
+A Jupyter notebook is an interactive computational environment that allows you to write and run code, visualise data, and write narrative text all in the same place. 
+It's a popular tool among data scientists and is commonly used for data analysis, machine learning, and scientific computing. 
+
+If you're new to Jupyter notebooks, here's a great place to start: 
+
+- `Introduction to Jupyter Notebooks <https://programminghistorian.org/en/lessons/jupyter-notebooks>`__
+- `How to use Jupyter Notebooks: A beginner's tutorial <https://www.dataquest.io/blog/jupyter-notebook-tutorial/>`__
+- more??
+
+You will notice that many of our "worked examples" are built in Jupyter notebooks so you can test run some of this code as soon as you have understood what the notebooks are, how to set them up on your computer, and how to run code in them.

docs/source/Contribution-guide/Code.rst

@@ -0,0 +1,45 @@
+How to add to or update the MapReader code
+===========================================
+
+MapReader's code is written in `Python <https://www.python.org/>`_. 
+There are a number of ways in which you can contribute to our code, these include:
+
+- Reviewing part of the code.
+- Adding new features.
+- Fixing bugs.
+- Adding clarity to docstrings.
+
+Before you begin
+-----------------
+
+If you already have an idea for changes to the MapReader code, please ensure your idea has a corresponding issue on the `MapReader repository <https://github.com/Living-with-machines/MapReader>`_ (or create one if needed). 
+If, on the other hand, you would like to contribute to the code but don't currently have an idea of what to work on, head to our `open issues <https://github.com/Living-with-machines/MapReader/issues>`_ tab and find something that interests you. 
+
+In either case, before you begin working, either assign yourself to the issue or comment on it saying you will be working on making the required changes. 
+
+You will then need to fork the `MapReader repository <https://github.com/Living-with-machines/MapReader>`_ in order to make your changes. 
+
+Style guide
+-----------
+
+When making your changes, please: 
+
+- Try to align to the `PEP 8 style guide for python code <https://peps.python.org/pep-0008/>`.
+- Try to use the numpy-style docstrings (as per `this link <https://numpydoc.readthedocs.io/en/latest/format.html#>_`). 
+- Ensure all docstrings are kept up to date and reflect any changes to code functionality you have made.
+- Add and run tests for your code.
+- If you add new dependencies, add these to our ``setup.py``.
+- If possible, update the MapReader user guide and worked examples to reflect your changes.
+
+When you are done making changes, please:
+
+- Run `black <https://black.readthedocs.io/en/stable/>` to reformat your code
+- Run `flake8 <https://flake8.pycqa.org/en/latest/index.html#>` to lint your code.
+
+When you are finished
+----------------------
+
+Once you are happy with the changes you have made, please create a new `pull request <https://github.com/Living-with-machines/MapReader/pulls>`_ to let us know you'd like us to review your code. 
+
+If possible, please link your pull request to any issue(s) your changes fix/address and write a thorough description of the changes you have made.
+