Ordeno la documentación para una primera versión que quede bien en Re…

…ad The Docs.
datosgobar · Nov 25, 2016 · c7d4ac9 · c7d4ac9
1 parent f857fee
commit c7d4ac9
Show file tree

Hide file tree

Showing 10 changed files with 138 additions and 67 deletions.
diff --git a/docs/HISTORY.md b/docs/HISTORY.md
@@ -0,0 +1,7 @@
+History
+===
+
+0.1.0 (2016-11-21)
+------------------
+
+* First release on PyPI.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,97 @@
+pydatajson
+===
+
+[![Coverage Status](https://coveralls.io/repos/github/datosgobar/pydatajson/badge.svg?branch=master)](https://coveralls.io/github/datosgobar/pydatajson?branch=master)
+[![Build Status](https://travis-ci.org/datosgobar/pydatajson.svg?branch=master)](https://travis-ci.org/datosgobar/pydatajson)
+[![PyPI](https://badge.fury.io/py/pydatajson.svg)](http://badge.fury.io/py/pydatajson)
+[![Stories in Ready](https://badge.waffle.io/datosgobar/pydatajson.png?label=ready&title=Ready)](https://waffle.io/datosgobar/pydatajson)
+[![Documentation Status](http://readthedocs.org/projects/pydatajson/badge/?version=latest)](http://data-cleaner.readthedocs.org/en/latest/?badge=latest)
+
+Paquete en python con herramientas para manipular y validar metadatos de catálogos de datos en formato data.json.
+
+
+* Licencia: MIT license
+* Documentación: https://pydatajson.readthedocs.io.
+
+
+## Instalación
+
+Instalar la librería debería ser tan sencillo como un `pip install`:
+
+* **Producción:** Desde cualquier parte
+
+```bash
+$ pip install pydatajson
+```
+
+* **Desarrollo:** Clonar este repositorio, y desde su raíz, ejecutar:
+```bash
+$ pip install -e .
+```
+
+## Uso
+
+La librería implementa un objeto, `DataJson`, con varios métodos para verificar la integridad de los archivos `data.json` y manipular su contenido. De particular interés son `is_valid_catalog` y `validate_catalog`.
+
+### Validar la estructura de un data.json contra el esquema por default que incluye la librería
+
+#### Archivo data.json local
+
+DataJson es capaz de validar archivos locales en cualquier directorio (accesible) siempre y cuando se provea el path absoluto a él.
+Por conveniencia, la carpeta [`tests/samples/`](tests/samples/) contiene varios ejemplos de `data.json`s bien y mal formados con distintos tipos de errores.
+
+```python
+from pydatajson import DataJson
+
+dj = DataJson()
+datajson_path = "tests/samples/full_data.json"
+validation_result = dj.is_valid_catalog(datajson_path)
+validation_report = dj.validate_catalog(datajson_path)
+
+print validation_result
+True
+
+print validation_report
+{ 
+    "status": "OK", 
+    "error": { 
+        "catalog": [], 
+        "dataset": [] 
+    }   
+}   
+```
+
+#### Archivo data.json remoto
+
+También es posible proveer una URL remota al archivo `data.json` de un portal productivo. Internamente, DataJson entiende que si el path del archivo a validar comienza con "http", se trata de una URL remota.
+
+```python
+datajson_url = "http://104.131.35.253/data.json"
+validation_result = dj.is_valid_catalog(datajson_url)
+validation_report = dj.validate_catalog(datajson_url)
+
+print validation_result
+False
+
+print validation_report
+{
+    "status": "ERROR",
+    "error": {
+        "catalog": ["Título del portal"],
+        "dataset": ["Dataset ejemplo 04", "Dataset ejemplo 03",
+                    "Dataset ejemplo 02", "Dataset ejemplo 01"]
+    }   
+}   
+```
+
+## Tests
+
+Los tests de la librería se desarrollaron con `nose`. Para correrlos, desde la raíz del repositorio:
+```
+$ pip install nose # Sólo la primera vez
+$ nosetests
+```
+
+## Créditos
+
+El validador de archivos `data.json` desarrollado no es más que un conveniente envoltorio alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el estándar definido por [JSONSchema.org](http://json-schema.org/).
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,6 +32,7 @@
 # version is used.
 sys.path.insert(0, project_root)
 
+import sphinx_rtd_theme
 import pydatajson
 
 # -- General configuration ---------------------------------------------
@@ -116,7 +117,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the

diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,18 +1,13 @@
-Welcome to pydatajson's documentation!
+Bienvenido a la documentación de pydatajson!
 ======================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
    README.md
-   installation
-   usage
-   contributing
    HISTORY.md
 
-Indices and tables
+Indices y tablas
 ==================
 
 * :ref:`genindex`

diff --git a/docs/installation.rst b/docs/installation.rst
diff --git a/docs/modules.rst b/docs/modules.rst
@@ -0,0 +1,7 @@
+pydatajson
+==========
+
+.. toctree::
+   :maxdepth: 4
+
+   pydatajson
diff --git a/docs/pydatajson.rst b/docs/pydatajson.rst
@@ -0,0 +1,22 @@
+pydatajson package
+==================
+
+Submodules
+----------
+
+pydatajson.pydatajson module
+----------------------------
+
+.. automodule:: pydatajson.pydatajson
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pydatajson
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/usage.rst b/docs/usage.rst
diff --git a/requirements_dev.txt b/requirements_dev.txt
@@ -11,3 +11,4 @@ PyYAML==3.11
 nose
 recommonmark
 twine
+sphinx_rtd_theme