Merge pull request #74 from jstockwin/doc-examples

[docs] Add examples to documentation

.github/scripts/docs.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+echo '#######################################################################'
+echo '#                             Building docs                           #'
+echo '#######################################################################'
+
+export SPHINXOPTS="-W"  # Treat warnings as errors
+
+make --directory $PROJECT_DIR/docs html
+
+DOCS_STATUS=$?
+if [[ ("$DOCS_STATUS" == 0) ]]; then
+  echo '#######################################################################'
+  echo '#                            Build succeded                           #'
+  echo '#######################################################################'
+  exit 0
+else
+  echo ''
+  echo '#######################################################################'
+  echo '#                            Build failed    !                        #'
+  echo '#######################################################################'
+  exit 1
+fi

.github/scripts/lint.sh

@@ -50,19 +50,19 @@ fi
 
 echo ''
 echo '#######################################################################'
-echo '#                             Running PyType                            #'
+echo '#                             Running PyType                          #'
 echo '#######################################################################'
 pytype $PROJECT_DIR --disable=pyi-error,import-error
 
 PYTYPE_STATUS=$?
 if [[ ("$PYTYPE_STATUS" == 0) ]]; then
   echo '#######################################################################'
-  echo '#                             PyType succeded                           #'
+  echo '#                             PyType succeded                         #'
   echo '#######################################################################'
 else
   echo ''
   echo '#######################################################################'
-  echo '#                             PyType failed    !                        #'
+  echo '#                             PyType failed    !                      #'
   echo '#######################################################################'
   LINTERS_FAILED=1
 fi

.github/workflows/continuous-integration.yml

@@ -10,11 +10,12 @@ jobs:
         with:
           username: "${{ secrets.DOCKER_USERNAME }}"
           password: "${{ secrets.DOCKER_PASSWORD }}"
-          image_name: py-pdf-parser/py-pdf-parser-test
+          image_name: jstockwin/py-pdf-parser-test
           image_tag: test
           dockerfile: dockerfiles/Dockerfile_tests
-          push_image_and_stages: false
       - name: Run linting
-        run: docker run --rm py-pdf-parser/py-pdf-parser-test:test .github/scripts/lint.sh
+        run: docker run --rm jstockwin/py-pdf-parser-test:test .github/scripts/lint.sh
       - name: Run test
-        run: docker run --rm py-pdf-parser/py-pdf-parser-test:test .github/scripts/test.sh
+        run: docker run --rm jstockwin/py-pdf-parser-test:test .github/scripts/test.sh
+      - name: Check docs build correctly
+        run: docker run --rm jstockwin/py-pdf-parser-test:test .github/scripts/docs.sh

CHANGELOG.md

@@ -6,8 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
-- Documentation is now hosted [here](https://py-pdf-parser.readthedocs.io/en/latest/).
+- Documentation is now hosted [here](https://py-pdf-parser.readthedocs.io/en/latest/). ([#71](https://github.com/jstockwin/py-pdf-parser/pull/71))
+- Added new examples to the documentation. ([#74](https://github.com/jstockwin/py-pdf-parser/pull/74))
 - Font filtering now caches the elements by font. ([#73](https://github.com/jstockwin/py-pdf-parser/pull/73)) (updated in [#78](https://github.com/jstockwin/py-pdf-parser/pull/78))
+- Font filtering now caches the elements by font. ([#73](https://github.com/jstockwin/py-pdf-parser/pull/73))
 
 ### Changed
 - This product is now complete enough for the needs of Optimor Ltd, however `jstockwin` is going to continue development as a personal project. The repository has been moved from `optimor/py-pdf-parser` to `jstockwin/py-pdf-parser`.

docker-compose.yml

@@ -33,9 +33,22 @@ tests:
     - .:/py-pdf-parser
   command: bash -c "nosetests ."
 
+# Run docs to re-build the docs once.
 docs:
   build: .
   dockerfile: dockerfiles/Dockerfile_tests
   volumes:
     - .:/py-pdf-parser
   command: make --directory docs html
+  environment:
+    - SPHINXOPTS="-W"
+
+# Use "up" to host the docs on port 8000, watching for changes.
+docs-autobuild:
+  build: .
+  dockerfile: dockerfiles/Dockerfile_tests
+  volumes:
+    - .:/py-pdf-parser
+  ports:
+    - "8000:8000"
+  command: make --directory docs livehtml

docs/Makefile

@@ -14,6 +14,9 @@ help:
 
 .PHONY: help Makefile
 
+livehtml:
+	sphinx-autobuild --host 0.0.0.0 -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/source/CHANGELOG.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/source/conf.py

@@ -32,6 +32,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -55,7 +56,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 
 # -- Extension configuration -------------------------------------------------

docs/source/examples/index.rst

@@ -0,0 +1,15 @@
+Examples
+========
+
+Below you can find links to the following examples:
+
+- The :ref:`simple-memo` example shows the very basics of using py-pdf-parser. You will see how to load a pdf document, start filtering the elements, and extract text from certain elements in the document.
+- The :ref:`order-summary` example explains how to use font mappings, sections, and how to extract simple tables.
+- The :ref:`more-tables` example explains tables in more detail, showing how to extract more complex tables.
+
+.. toctree::
+
+   simple_memo
+   order_summary
+   more_tables
+