[IV-21-22] Objetivo 3

README.md

@@ -1,11 +1,16 @@
 # Faux
 
-Faux is a tool aimed to reduce misinformation along the web.
+Faux is a tool aimed to reduce misinformation along the web. It analyzes 
+texts and headlines to categorize them as fake news, clickbait articles 
+or seemingly-normal-things. 
 
-It analyzes texts and headlines to categorize them as fake news, 
-clickbait articles or seemingly-normal-things. On top of that, 
-it provides information about how likely this prediction is based 
-on its source and topic (health, economics, etc).
+## Table of contents
+
+- [Why and how](https://github.com/arguellesm/faux#why-and-how)
+- [Dependencies](https://github.com/arguellesm/faux#dependencies)
+- [Installation](https://github.com/arguellesm/faux#installation)
+- [Usage](https://github.com/arguellesm/faux#usage)
+- [Documentation](https://github.com/arguellesm/faux#read-the-docs)
 
 ## Why and how
 
@@ -18,6 +23,54 @@ Faux takes news and headlines as input and applies heuristics to
 classify them. Being a cloud service, it's constantly being 
 updated and refined to achieve the best possible outcome.
 
+## Requirements
+
+- Python **3.5+**.
+
+## Dependencies
+
+Managed with [Poetry](https://python-poetry.org/), check out [`pyproject.toml`](pyproject.toml).
+
+## Installation
+
+#### Poetry
+
+Poetry will manage and install dependencies, ensuring that your 
+_Faux_ built is ready to use. According to the [official Poetry
+documentation](https://python-poetry.org/docs/#installation), 
+install with:
+
+```
+curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+
+```
+
+#### This repository
+
+[Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+this repository and run:
+
+```
+cd faux
+poetry install
+```
+
+This will install all dependencies.
+
+## Usage
+
+#### Syntax check
+
+You can check the syntax of every `.py` file under `src` with:
+
+```
+poetry shell
+inv check
+```
+
 ## Read the docs!
 
-Feel free to read a bit more about the project [here](docs/README.md).
+Feel free to read a bit more about the project:
+
+- [Users and user journey](docs/users.md)
+- [Development tools and why](docs/dev_tools.md)

docs/dev_tools.md

@@ -0,0 +1,44 @@
+## Development tools and why
+
+### [Poetry](https://python-poetry.org/)
+
+We use Poetry as a dependency management tool to keep track
+of the libraries needed to build the project. This makes it 
+easier for anyone to replicate the project. 
+
+The main alternatives to Poetry are Pip and Pipenv:
+
+- [Pip](https://pypi.org/project/pip/) 
+
+  Pip is a package manager, meaning that dependency updates 
+  must be done manually. This will defeat the purpose of using
+  it for automation.
+
+- [Pipenv](https://pipenv.pypa.io/en/latest/)
+
+  The main differences between Pipenv and Poetry are that Poetry
+  has much faster install times and supports `pyproject.toml`, 
+  which is the official Python file for dependency management (see
+  [PEP 518](https://www.python.org/dev/peps/pep-0518/#file-format)).
+
+
+### [Invoke](https://www.pyinvoke.org/)
+
+Invoke is our task runner of choice. It inherits a minimal yet 
+powerful philosophy from GNU Make and is broadly used among the 
+Python community.
+
+Some alternatives are:
+
+- [Pypyr](https://pypyr.io/docs/)
+
+  Pypyr uses pipelines defined in yaml. There are many differences
+  between these two, but the key for choosing one over the other
+  was being more used to Python and finding easier to work with 
+  Invoke's approach.
+
+- [doit](https://pydoit.org/contents.html#)
+
+  _doit_ has quite a similar approach to Invoke and uses Python as 
+  well. However, Invoke's community is much bigger, which usually
+  translates to more resources and easier troubleshooting.

iv.yaml

@@ -1,4 +1,9 @@
 lenguaje: python
+
 entidad:
   - src/article.py
   - src/globals.py
+
+automatizar:
+  fichero: tasks.py
+  orden: inv