From 6a558df4b3b372fc460e300b8e9bfb49f418e727 Mon Sep 17 00:00:00 2001
From: Charles Gaillard <charles@mindee.co>
Date: Tue, 6 Jul 2021 09:46:10 +0200
Subject: [PATCH] docs: Add export example in README (#348)

* feat: add export example

* fix: typing

* refacto: moved to the docs

* refacto: moved to the docs

* fix: readme link

* fix: typos
---
 README.md                 |  7 ++--
 docs/source/documents.rst |  1 +
 docs/source/models.rst    | 68 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5992784ad4..06f68e6808 100644
--- a/README.md
+++ b/README.md
@@ -63,12 +63,15 @@ result.show(doc)
 
 ![DocTR example](https://github.com/mindee/doctr/releases/download/v0.1.1/doctr_example_script.gif)
 
-or export them to JSON format (to get a better understanding of our document model, check our [documentation](https://mindee.github.io/doctr/documents.html#document-structure)):
+The ocr_predictor returns a `Document` object with a nested structure (with `Page`, `Block`, `Line`, `Word`, `Artefact`). 
+To get a better understanding of our document model, check our [documentation](https://mindee.github.io/doctr/documents.html#document-structure):
+
+You can also export them as a nested dict, more appropriate for JSON format:
 
 ```python
 json_output = result.export()
 ```
-
+For examples & further details about the export format, please refer to [this section](https://mindee.github.io/doctr/models.html#export-model-output) of the documentation
 
 ## Installation
 
diff --git a/docs/source/documents.rst b/docs/source/documents.rst
index 655730073e..86a6ee0101 100644
--- a/docs/source/documents.rst
+++ b/docs/source/documents.rst
@@ -7,6 +7,7 @@ doctr.documents
 The documents module enables users to easily access content from documents and export analysis
 results to structured formats.
 
+.. _document_structure:
 
 Document structure
 ------------------
diff --git a/docs/source/models.rst b/docs/source/models.rst
index 9830c6c153..650d387612 100644
--- a/docs/source/models.rst
+++ b/docs/source/models.rst
@@ -178,6 +178,74 @@ Those architectures involve one stage of text detection, and one stage of text r
 
 .. autofunction:: doctr.models.zoo.ocr_predictor
 
+Export model output
+^^^^^^^^^^^^^^^^^^^^
+
+The ocr_predictor returns a `Document` object with a nested structure (with `Page`, `Block`, `Line`, `Word`, `Artefact`). 
+To get a better understanding of our document model, check our :ref:`document_structure` section
+
+Here is a typical `Document` layout::
+
+  Document(
+    (pages): [Page(
+      dimensions=(340, 600)
+      (blocks): [Block(
+        (lines): [Line(
+          (words): [
+            Word(value='No.', confidence=0.91),
+            Word(value='RECEIPT', confidence=0.99),
+            Word(value='DATE', confidence=0.96),
+          ]
+        )]
+        (artefacts): []
+      )]
+    )]
+  )
+
+You can also export them as a nested dict, more appropriate for JSON format::
+
+  json_output = result.export()
+
+For reference, here is the JSON export for the same `Document` as above::
+
+  {
+    'pages': [
+        {
+            'page_idx': 0,
+            'dimensions': (340, 600),
+            'orientation': {'value': None, 'confidence': None},
+            'language': {'value': None, 'confidence': None},
+            'blocks': [
+                {
+                    'geometry': ((0.1357421875, 0.0361328125), (0.8564453125, 0.8603515625)),
+                    'lines': [
+                        {
+                            'geometry': ((0.1357421875, 0.0361328125), (0.8564453125, 0.8603515625)),
+                            'words': [
+                                {
+                                    'value': 'No.',
+                                    'confidence': 0.914085328578949,
+                                    'geometry': ((0.5478515625, 0.06640625), (0.5810546875, 0.0966796875))
+                                },
+                                {
+                                    'value': 'RECEIPT',
+                                    'confidence': 0.9949972033500671,
+                                    'geometry': ((0.1357421875, 0.0361328125), (0.51171875, 0.1630859375))
+                                },
+                                {
+                                    'value': 'DATE',
+                                    'confidence': 0.9578408598899841,
+                                    'geometry': ((0.1396484375, 0.3232421875), (0.185546875, 0.3515625))
+                                }
+                            ]
+                        }
+                    ],
+                    'artefacts': []
+                }
+            ]
+        }
+    ]
+  }
 
 Model export
 ------------