Documentation

README.md

@@ -46,7 +46,9 @@ Para Python 3:
 Documentación y uso
 ===================
 
-El directorio docs/ contiene toda la documentación.
+El directorio docs/ contiene toda la documentación. Puedes generarla ejecutando:
+
+    cd docs && make html
 
 Puedes consultar la versión online en http://bormeparser.readthedocs.org/es/latest/.
 

bormeparser/borme.py

@@ -89,4 +89,4 @@ def from_file(filename):
         raise NotImplementedError
 
     def __repr__(self):
-        return "<Borme(%d-%d-%d) seccion:%s provincia:%s>" % (self.date.year, self.date.month, self.date.day, self.seccion, self.provincia)
+        return "<Borme(%s) seccion:%s provincia:%s>" % (self.date, self.seccion, self.provincia)

bormeparser/download.py

@@ -60,7 +60,7 @@ def download_pdf(date, filename, seccion, provincia):
     downloaded = download_url(url, filename)
 
     if downloaded:
-        return Borme(date, seccion, provincia, filename=filename)
+        return Borme(date, seccion, provincia, filename=filename, num=0) # FIXME: num
     else:
         return False
 

bormeparser/tests/test_bormeparser.py

@@ -138,7 +138,7 @@ def test_download_pdf(self):
         self.assertEqual(os.path.getsize(path), 202795)
         os.unlink(path)
 
-    def test_download_pdf(self):
+    def test_download_pdfs(self):
         # Maybe these are too many files to download
         pass
 

docs/backends.rst

@@ -0,0 +1,20 @@
+Backends
+========
+
+Bormeparser soporta diferentes backends a la hora de parsear los archivos PDF.
+
+Usar un backend específico
+--------------------------
+
+.. code-block:: python
+
+    import bormeparser
+
+    parser = bormeparser.backend.pypdf2.parser()
+    parser.download(...)
+
+
+Implementar un nuevo backend
+----------------------------
+
+base.py

docs/conf.py

@@ -110,7 +110,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #html_theme = 'alabaster'
-html_theme = 'default'
+html_theme = 'classic'
 
 # 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

docs/contribution.rst

@@ -1,4 +1,7 @@
-Cotnribuir
+Contribuir
 ==========
 
-Para contribuir...
+Puedes mandar tus Pull Requests directamente a través de GitHub, donde también hay una lista de issues
+puedes ayudar a arreglar.
+
+https://github.com/PabloCastellano/bormeparser/issues

docs/index.rst

@@ -13,6 +13,8 @@ Contenido:
 
     Introducción <introduction>
     Instalación <installation>
+    Tutorial <tutorial>
+    Backends <backends>
     Contribuir <contribution>
     Lista de cambios <changelog>
 

docs/installation.rst

@@ -1,4 +1,13 @@
 Instalación
 ===========
 
+Puedes obtener bormeparser sencillamente desde PyPI::
 
+    pip install bormeparser
+
+O si lo prefieres, puedes clonar el repositorio e instalarlo desde ahí, compilando previamente sus dependencias::
+
+    sudo apt-get install python3-dev libxslt1-dev
+    git clone https://github.com/PabloCastellano/bormeparser
+    cd bormeparser
+    pip install bormeparser

docs/introduction.rst

@@ -1,4 +1,26 @@
 Introducción
 ============
 
-bormeparser es...
+**bormeparser** es una librería de Python para parsear los archivos del BORME (Boletín Oficial del Registro Mercantil en España).
+
+Qué es BORME
+------------
+
+El **Boletín Oficial del Registro Mercantil** es un documento publicado diariamente por el Registro Mercantil Central (RMC)
+en España que contiene un listado de las últimas sociedades creadas y disueltas así como otros datos que las empresas
+están obligadas a comunicar.
+
+La librería aprovecha que desde la aprobación de `esta ley`_,
+desde el año 2009 el BORME se publica también en formato electrónico con la misma validez que su versión en papel.
+
+Los BORMEs se publican en http://boe.es/diario_borme/.
+
+Desgraciadamente debido al acuerdo actual con el Registro Mercantil, no pueden publicar todos los datos en un formato
+útil y reutilizable como XML o JSON y los datos más interesantes están solo disponibles en los archivos PDF.
+
+Puedes leer más sobre ello en:
+
+- Wikipedia: `https://es.wikipedia.org/wiki/Boletín_Oficial_del_Registro_Mercantil`_
+
+.. _esta ley: http://www.boe.es/buscar/doc.php?id=BOE-A-2008-19826
+.. _https://es.wikipedia.org/wiki/Boletín_Oficial_del_Registro_Mercantil: https://es.wikipedia.org/wiki/Boletín_Oficial_del_Registro_Mercantil

docs/tutorial.rst

@@ -0,0 +1,53 @@
+Tutorial
+========
+
+Uso básico
+----------
+
+bormeparser proporciona distintas funciones para tratar los archivos del BORME.
+
+Empezamos con las funciones para generar las urls de descarga:
+
+.. code-block:: python
+
+    import bormeparser
+    date = (2015, 6, 2)
+    xml_url = bormeparser.get_url_xml(date)
+    pdf_url = bormeparser.get_url_pdf(date, bormeparser.SECCION.A, bormeparser.PROVINCIA.MALAGA)
+
+.. code-block:: python
+
+    >>> print(xml_url)
+    http://www.boe.es/diario_borme/xml.php?id=BORME-S-20150602
+    >>> print(pdf_url)
+    http://boe.es/borme/dias/2015/06/02/pdfs/BORME-A-2015-102-29.pdf
+
+Pero podemos usar otras funciones para descargar el BORME directamente de ese día:
+
+.. code-block:: python
+
+    import bormeparser
+    
+    date = (2015, 6, 2)
+    path = '/tmp/BORME-A-2015-102-29.pdf'
+    borme = bormeparser.download_pdf(date, path, bormeparser.SECCION.A, bormeparser.PROVINCIA.MALAGA)
+
+Si no ha habido ningún error (problema de conexión, el BORME de esa fecha no existe, ...) la variable borme
+es una instancia de Borme:
+
+.. code-block:: python
+
+    >>> print(borme)
+    <Borme(2015-06-02) seccion:A provincia:29>
+
+Para conocer la url de un PDF, bormeparser internamente descarga el archivo XML del día y ahí encuentra la ruta.
+Podemos obtener dicho archivo XML así:
+
+.. code-block:: python
+
+    >>> bormeparser.download_xml(date, '/tmp/20150602.xml')
+    True
+
+
+Uso avanzado
+------------