atualiza as instruções sobre como criar spiders (turicas#149)

README.en.md

@@ -124,15 +124,28 @@ We're changing the way we upload the data to make the job easier for volunteers
 
 - It's **required** that you create it using `scrapy`;
 - **Do Not** use `pandas`, `BeautifulSoap`, `requests` or other unnecessary libraries (the standard Python lib already has lots of useful libs, `scrapy` with XPath is already capable of handling most of the scraping and `rows` is already a dependency of this repository);
+- Create a file named `web/spiders/spider_xx.py`, where `xx` is the state
+  acronym, in lower case. Create a new class and inherit from the
+  `BaseCovid19Spider` class, from `base.py`. The state acronym, in two upper
+  case characters, must be an attribute of the class and use `self.state`.
+  See the examples that have already been implemented;
 - There must be an easy way to make the scraper collect reports and cases for an specific date (but it should be able to identify which dates the data is available for and to capture several dates too);
-- The parsing method must return (with `yield`) a dictionary with the following keys:
-  - `date`: in the format `"YYYY-MM-DD"`
-  - `state`: the state initials, with 2 characters in caps (must be an attribute from the class of the spider and use `self.state`)
-  - `city` (city name or blank, in case its the state's value, it must be `None`)
-  - `place_type`: use `"city"` when it's municipal data and `"state"` it's from the whole state
-  - `confirmed`: integer, number of cases confirmed (or `None`)
-  - `deaths`: integer, number of deaths on that day (or `None`)
-  - **ATTENTION**:	the scraper must always return a register to the state that *isn't* the sum of values by city (this data should be extracted by a row named "total in state" in the report) - this row will have the column `city` with the value `None` and `place_type` with `state` - this data must come filled as being the sum of all municipal values *in case the report doesn't have the totalling data*
+- The data can be read from the tallies by municipality or from individual case
+  microdata. In that latter case, the scraper must tally up itself the
+  municipal numbers;
+- The `parse` method must cal the `self.add_report(date, url)` method, with
+  `date` being the report date and `url` the URL of the information source;
+- For each municipality in the state, call the `self.add_city_case` method with
+  the following parameters:
+  - `city`: name of the municipality
+  - `confirmed`: integer, number of confirmed cases (or `None`)
+  - `death`: integer, number of deaths on that day (or `None`)
+- Read the state totals from the source of information, if available. One
+  should sum up the numbers of each municipality *only if that information
+  is not available in the original source*. Include the total numbers of the
+  state by calling the `self.add_state_case` method. The parameters are the
+  same as the ones in the method used for the municipality, except for the
+  omission of the `city` parameter;
 - When possible, use automated tests;
 
 Right now we don't have much time available for reviews, so **please**, only create a pull request with code of a new scraper if you can fulfill the requirements above.

README.md

@@ -127,6 +127,42 @@ Procure o seu estado [nas issues desse
 repositório](https://github.com/turicas/covid19-br/issues) e vamos conversar
 por lá.
 
+### Criando Scrapers
+
+Estamos mudando a forma de subida dos dados para facilitar o trabalho dos voluntários e deixar o processo mais robusto e confiável e, com isso, será mais fácil que robôs possam subir também os dados; dessa forma, os scrapers ajudarão *bastante* no processo. Porém, ao criar um scraper é importante que você siga algumas regras:
+
+- **Necessário** fazer o scraper usando o `scrapy`;
+- **Não usar** `pandas`, `BeautifulSoap`, `requests` ou outras bibliotecas
+  desnecessárias (a std lib do Python já tem muita biblioteca útil, o `scrapy`
+  com XPath já dá conta de boa parte das raspagens e `rows` já é uma
+  dependência desse repositório);
+- Criar um arquivo `web/spiders/spider_xx.py`, onde `xx` é a sigla do estado,
+  em minúsculas. Criar uma nova classe e herdar da classe `BaseCovid19Spider`,
+  do `base.py`. A sigla do estado, com 2 caracteres maiúsculos, deve ser um
+  atributo da classe do spider e usar `self.state`. Veja os exemplos já
+  implementados;
+- Deve existir alguma maneira fácil de fazer o scraper coletar os boletins e
+  casos para uma data específica (mas ele deve ser capaz de identificar para
+  quais datas os dados disponíveis e de capturar várias datas também);
+- A leitura pode ser feita a partir de contagens por município ou de microdados
+  de casos individuais. Neste caso, é necessário que o próprio scraper calcule
+  os totais por município;
+- O método `parse` deve chamar o método `self.add_report(date, url)`, sendo
+  `date` a data do relatório e `url` a URL da fonte de informação;
+- Para cada município no estado, chamar o método `self.add_city_case` com os
+  seguintes parâmetros:
+  - `city`: nome do município
+  - `confirmed`: inteiro, número de casos confirmados (ou `None`)
+  - `death`: inteiro, número de óbitos naquele dia (ou `None`)
+- Ler os totais do estado a partir da fonte da informação, se estiver
+  disponível. Deve-se somar os números de cada município *somente se essa
+  informação não estiver disponível na fonte original*. Incluir os números
+  totais no estado chamando o método
+  `self.add_state_case`. Os parâmetros são os mesmos do método usado para o
+  município, exceto pela omissão do parâmetro `city`;
+- Quando possível, use testes automatizados.
+
+Nesse momento não temos muito tempo disponível para revisão, então **por favor**, só crie um *pull request* com código de um novo scraper caso você possa cumprir os requisitos acima.
 
 ## Instalando