Translate using-the-toolbox.rst (#72)

Closes #69
okfn-brasil · Oct 9, 2023 · b46af8f · b46af8f
2 parents b411d7f + 455790b
commit b46af8f
Show file tree

Hide file tree

Showing 2 changed files with 108 additions and 12 deletions.
diff --git a/docs/using-the-toolbox.rst b/docs/using-the-toolbox.rst
@@ -1,4 +1,92 @@
 Using the Toolbox
 ========================
 
-Soon
+|python_version_img|
+|pypi_img|
+
+The objective of `querido-diario-toolbox`_ is to equip Querido Diário's (QD) 
+community with the tools necessary to conduct their own analyses and data 
+manipulations using data obtained through QD. Additionally, the library 
+will be integrated into the production applications used by Querido Diário, 
+meaning that anyone using the library will be able to locally reproduce the 
+same data processing steps performed by QD.
+
+The library provides many levels of abstractions to work with the data. 
+Ranging from simple text cleaning using strings to converting files from 
+various formats into plain text.
+
+Installing
+----------
+
+.. code-block:: python
+
+    pip install querido-diario-toolbox
+
+Currently, `querido-diario-toolbox` is compatible with Python 3.8+.
+
+To perform the text extractions it's necessary to install `Tesseract OCR`_, as 
+well as the ``.jar`` files from `Apache Tika`_ (last tested version: 1.24.1) and 
+`Tabula`_ (last tested version: v1.0.4) accessible in order to pass their file 
+paths as arguments.
+
+Use case
+---------------
+
+More elaborate examples are available in the `examples`_ folder. You can view 
+them (and interact if you wish) using `Jupyter`_ notebooks.
+
+Removing unnecessary spaces in text
+............................................
+
+.. code-block:: python
+
+    from querido_diario_toolbox.process.text_process import remove_breaks
+
+    texto = "\n\n\nThis text has many      white spaces\n\n \nunnecessary.\n"
+
+    remove_breaks(texto)
+    'This text has many white spaces unnecessary.'
+
+Finding valid `CNPJs`_ in text
+.....................................
+
+.. code-block:: python
+
+    from querido_diario_toolbox.process.edition_process import extract_and_validate_cnpj
+    
+    texto = "The companies with valid CNPJs 00.000.000/0001-91 and 00.360.305/0001-04 exist, but the one with CNPJ 12.123.123/1234.12 does not exist..."
+    
+    extract_and_validate_cnpj(texto)
+    ['00.000.000/0001-91', '00.360.305/0001-04']
+
+Converting file from closed format to plain text and extracting metadata
+............................................................................
+
+.. code-block:: python
+
+    from querido_diario_toolbox import Gazette
+    from querido_diario_toolbox.etl.text_extractor import create_text_extractor
+
+    config = {"apache_tika_jar": "caminho/apache/tika/jar/tika-app-1.24.1.jar"}
+    extrator = create_text_extractor(config)
+
+    diario = Gazette(filepath="caminho/diario/fechado/diario.pdf")
+
+    extrator.extract_text(diario)
+    extrator.extract_metadata(diario)
+    extrator.load_content(diario)
+
+After the execution of ``extrator.load_content(diario)``, two files (a ``.txt`` 
+with pure text and a ``.json`` with metadata) will be created.
+
+.. |python_version_img| image:: https://img.shields.io/pypi/pyversions/querido-diario-toolbox
+                        :target: https://pypi.org/project/querido-diario-toolbox/
+.. |pypi_img| image:: https://img.shields.io/pypi/v/querido-diario-toolbox
+              :target: https://pypi.org/project/querido-diario-toolbox/
+.. _querido-diario-toolbox: https://pypi.org/project/querido-diario-toolbox/
+.. _Tesseract OCR: https://tesseract-ocr.github.io/tessdoc/
+.. _Apache Tika: https://tika.apache.org/download.html
+.. _examples: https://github.com/okfn-brasil/querido-diario-toolbox/tree/main/examples
+.. _Tabula: https://github.com/tabulapdf/tabula-java/releases
+.. _Jupyter: https://jupyter.org/
+.. _CNPJs: https://en.wikipedia.org/wiki/CNPJ
diff --git a/docs/utilizando-a-toolbox.rst b/docs/utilizando-a-toolbox.rst
@@ -4,13 +4,16 @@ Utilizando a Toolbox do Querido Diário
 |python_version_img|
 |pypi_img|
 
-.. *`Click here`_ to read this article in english.*
-
-O objetivo da `querido-diario-toolbox` é dar à comunidade do Querido Diário o ferramental para executar suas próprias análises e manipulações com os dados
-que são obtidos pelo QD. Além disso, a biblioteca também será integrada nas aplicações utilizadas em produção pelo Querido Diário. Ou seja, quem utilizar a biblioteca poderá reproduzir localmente as mesmas etapas de
+O objetivo da `querido-diario-toolbox`_ é dar à comunidade do Querido Diário o 
+ferramental para executar suas próprias análises e manipulações com os dados
+que são obtidos pelo QD. Além disso, a biblioteca também será integrada nas 
+aplicações utilizadas em produção pelo Querido Diário. Ou seja, quem utilizar a 
+biblioteca poderá reproduzir localmente as mesmas etapas de
 processamento que o QD realiza.
 
-A biblioteca dá diferentes níveis de abstrações para trabalhar com os dados. Desde uma simples limpeza de texto a partir de strings até conversão de arquivos de vários formatos para texto puro.
+A biblioteca dá diferentes níveis de abstrações para trabalhar com os dados. 
+Desde uma simples limpeza de texto a partir de strings até conversão de arquivos
+de vários formatos para texto puro.
 
 
 Instalação
@@ -22,12 +25,16 @@ Instalação
 
 Atualmente, a `querido-diario-toolbox` é compatível com Python 3.8+.
 
-Para executar extrações de texto é necessário ter o `Tesseract OCR`_ instalado. Assim como ter os `.jar` do `Apache Tika`_ (última versão testada: 1.24.1) e `Tabula`_ (última versão testada: v1.0.4) acessíveis para poder passar seus caminhos de arquivo como argumentos.
+Para executar extrações de texto é necessário ter o `Tesseract OCR`_ instalado. 
+Assim como ter os ``.jar`` do `Apache Tika`_ (última versão testada: 1.24.1) e 
+`Tabula`_ (última versão testada: v1.0.4) acessíveis para poder passar seus 
+caminhos de arquivo como argumentos.
 
 Exemplos de uso
 ---------------
 
-Exemplos mais elaborados estão disponíveis na pasta `./examples`_. Você pode visualizá-los (e interagir se desejar) utilizando notebooks `Jupyter`_.
+Exemplos mais elaborados estão disponíveis na pasta `examples`_. Você pode 
+visualizá-los (e interagir se desejar) utilizando notebooks `Jupyter`_.
 
 Removendo espaços desnecessários em um texto
 ............................................
@@ -36,7 +43,7 @@ Removendo espaços desnecessários em um texto
 
     from querido_diario_toolbox.process.text_process import remove_breaks
 
-    texto = "\n\n\nEste texto tem vários      espaços em branco\n\n \ndesnecessários.\n"
+    texto = "\n\n\nEste texto tem vários   espaços em branco\n\n \ndesnecessários.\n"
 
     remove_breaks(texto)
     'Este texto tem vários espaços em branco desnecessários.'
@@ -70,17 +77,18 @@ Convertendo arquivo de formato fechado para texto puro e extraindo metadados
     extrator.extract_metadata(diario)
     extrator.load_content(diario)
 
-Após a execução de `extrator.load_content(diario)`, dois arquivos (um `.txt` com o texto puro e um `.json` com os metadados) serão criados.
+Após a execução de ``extrator.load_content(diario)``, dois arquivos (um ``.txt``
+com o texto puro e um ``.json`` com os metadados) serão criados.
 
 
-.. _Click here: how-to-use-toolbox.rst
 .. |python_version_img| image:: https://img.shields.io/pypi/pyversions/querido-diario-toolbox
                         :target: https://pypi.org/project/querido-diario-toolbox/
 .. |pypi_img| image:: https://img.shields.io/pypi/v/querido-diario-toolbox
               :target: https://pypi.org/project/querido-diario-toolbox/
+.. _querido-diario-toolbox: https://pypi.org/project/querido-diario-toolbox/
 .. _Tesseract OCR: https://tesseract-ocr.github.io/tessdoc/
 .. _Apache Tika: https://tika.apache.org/download.html
-.. _./examples: examples
+.. _./examples: https://github.com/okfn-brasil/querido-diario-toolbox/tree/main/examples
 .. _Tabula: https://github.com/tabulapdf/tabula-java/releases
 .. _Jupyter: https://jupyter.org/