diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4f4c2013..b7ff31cb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ Kenneth Reitz has also written an [essay](https://www.kennethreitz.org/essays/be
As the [Requests Code Of Conduct](http://docs.python-requests.org/en/master/dev/contributing/#be-cordial) states, **all contributions are welcome**, as long as everyone involved is treated with respect.
-## Your First Contribution
+## Your first contribution
A great way to start contributing to Camelot is to pick an issue tagged with the [Contributor Friendly](https://github.com/socialcopsdev/camelot/labels/Contributor%20Friendly) tag or the [Level: Easy](https://github.com/socialcopsdev/camelot/labels/Level%3A%20Easy) tag. If you're unable to find a good first issue, feel free to contact the maintainer.
@@ -26,19 +26,17 @@ To install the dependencies needed for development, you can use pip:
$ pip install camelot-py[dev]
-### Alternatively
-
-You can clone the project repository, and install using pip:
+Alternatively, you can clone the project repository, and install using pip:
-$ pip install .[dev]
+$ pip install ".[dev]"
## Pull Requests
-### Submit a Pull Request
+### Submit a pull request
-The preferred workflow for contributing to Camelot is to fork the [project repository](https://github.com/socialcopsdev/camelot) on GitHub, clone, develop on a branch and then finally submit a pull request. Steps:
+The preferred workflow for contributing to Camelot is to fork the [project repository](https://github.com/socialcopsdev/camelot) on GitHub, clone, develop on a branch and then finally submit a pull request. Here are the steps:
1. Fork the project repository. Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub.
@@ -73,7 +71,7 @@ $ git push -u origin my-feature
Now it's time to go to the your fork of Camelot and create a pull request! You can [follow these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) to do this.
-### Work on your Pull Request
+### Work on your pull request
We recommend that your pull request complies with the following rules:
@@ -81,7 +79,7 @@ We recommend that your pull request complies with the following rules:
- In case your pull request contains function docstrings, make sure you follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) format. All function docstrings in Camelot follow this format. Moreover, following the format will make sure that the API documentation is generated flawlessly.
-- Make sure your commit messages follow [the seven rules of a great git commit message](https://chris.beams.io/posts/git-commit/).
+- Make sure your commit messages follow [the seven rules of a great git commit message](https://chris.beams.io/posts/git-commit/):
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
@@ -104,15 +102,15 @@ Writing documentation, function docstrings, examples and tutorials is a great wa
It is written in [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText), with [Sphinx](http://www.sphinx-doc.org/en/master/) used to generate these lovely HTML files that you're currently reading (unless you're reading this on GitHub). You can edit the documentation using any text editor and then generate the HTML output by running `make html` in the `docs/` directory.
-The function docstrings are written using the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) extension for Sphinx. Make sure you check out its format guidelines, before you start writing one.
+The function docstrings are written using the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) extension for Sphinx. Make sure you check out its format guidelines before you start writing one.
## Filing Issues
-We use [GitHub issues](https://docs.pytest.org/en/latest/) to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), it is advisable to use GitHub search to look for existing issues (both open and closed) that may be similar.
+We use [GitHub issues](https://docs.pytest.org/en/latest/) to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), please use GitHub search to look for existing issues (both open and closed) that may be similar.
### Questions
-Please don't use GitHub issues for support questions, a better place for them would be [Stack Overflow](http://stackoverflow.com). Make sure you tag them using the `python-camelot` tag.
+Please don't use GitHub issues for support questions. A better place for them would be [Stack Overflow](http://stackoverflow.com). Make sure you tag them using the `python-camelot` tag.
### Bug Reports
diff --git a/README.md b/README.md
index ffdb09ae..8c9fd565 100644
--- a/README.md
+++ b/README.md
@@ -7,11 +7,11 @@
[](https://travis-ci.org/socialcopsdev/camelot) [](https://codecov.io/github/socialcopsdev/camelot?branch=master)
[](https://pypi.org/project/camelot-py/) [](https://pypi.org/project/camelot-py/) [](https://pypi.org/project/camelot-py/)
-**Camelot** is a Python library which makes it easy for *anyone* to extract tables from PDF files!
+**Camelot** is a Python library that makes it easy for *anyone* to extract tables from PDF files!
---
-**Here's how you can extract tables from PDF files.** Check out the PDF used in this example, [here](https://github.com/socialcopsdev/camelot/blob/master/docs/_static/pdf/foo.pdf).
+**Here's how you can extract tables from PDF files.** Check out the PDF used in this example [here](https://github.com/socialcopsdev/camelot/blob/master/docs/_static/pdf/foo.pdf).
>>> import camelot
@@ -43,14 +43,14 @@
There's a [command-line interface](https://camelot-py.readthedocs.io/en/latest/user/cli.html) too!
-**Note:** Camelot only works with text-based PDFs and not scanned documents. If you can click-and-drag to select text in your table in a PDF viewer, then your PDF is text-based.
+**Note:** Camelot only works with text-based PDFs and not scanned documents. If you can click and drag to select text in your table in a PDF viewer, then your PDF is text-based.
## Why Camelot?
-- **You are in control**: Unlike other libraries and tools which either give a nice output or fail miserably (with no in-between), Camelot gives you the power to tweak table extraction. (Since everything in the real world, including PDF table extraction, is fuzzy.)
-- **Metrics**: *Bad* tables can be discarded based on metrics like accuracy and whitespace, without ever having to manually look at each table.
-- Each table is a **pandas DataFrame**, which enables seamless integration into [ETL and data analysis workflows](https://gist.github.com/vinayak-mehta/e5949f7c2410a0e12f25d3682dc9e873).
-- **Export** to multiple formats, including json, excel and html.
+- **You are in control.**: Unlike other libraries and tools which either give a nice output or fail miserably (with no in-between), Camelot gives you the power to tweak table extraction. (This is important since everything in the real world, including PDF table extraction, is fuzzy.)
+- *Bad* tables can be discarded based on **metrics** like accuracy and whitespace, without ever having to manually look at each table.
+- Each table is a **pandas DataFrame**, which seamlessly integrates into [ETL and data analysis workflows](https://gist.github.com/vinayak-mehta/e5949f7c2410a0e12f25d3682dc9e873).
+- **Export** to multiple formats, including JSON, Excel and HTML.
See [comparison with other PDF table extraction libraries and tools](https://github.com/socialcopsdev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools).
diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst
index 16f2a42d..e0602f13 100644
--- a/docs/dev/contributing.rst
+++ b/docs/dev/contributing.rst
@@ -24,7 +24,7 @@ As the `Requests Code Of Conduct`_ states, **all contributions are welcome**, as
.. _Requests Code Of Conduct: http://docs.python-requests.org/en/master/dev/contributing/#be-cordial
-Your First Contribution
+Your first contribution
-----------------------
A great way to start contributing to Camelot is to pick an issue tagged with the `Contributor Friendly`_ or the `Easy`_ tags. If you're unable to find a good first issue, feel free to contact the maintainer.
@@ -39,13 +39,17 @@ To install the dependencies needed for development, you can use pip::
$ pip install camelot-py[dev]
+Alternatively, you can clone the project repository, and install using pip::
+
+ $ pip install ".[dev]"
+
Pull Requests
-------------
-Submit a Pull Request
+Submit a pull request
^^^^^^^^^^^^^^^^^^^^^
-The preferred workflow for contributing to Camelot is to fork the `project repository`_ on GitHub, clone, develop on a branch and then finally submit a pull request. Steps:
+The preferred workflow for contributing to Camelot is to fork the `project repository`_ on GitHub, clone, develop on a branch and then finally submit a pull request. Here are the steps:
.. _project repository: https://github.com/socialcopsdev/camelot
@@ -76,7 +80,7 @@ Now it's time to go to the your fork of Camelot and create a pull request! You c
.. _follow these instructions: https://help.github.com/articles/creating-a-pull-request-from-a-fork/
-Work on your Pull Request
+Work on your pull request
^^^^^^^^^^^^^^^^^^^^^^^^^
We recommend that your pull request complies with the following guidelines:
@@ -89,7 +93,7 @@ We recommend that your pull request complies with the following guidelines:
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
-- Make sure your commit messages follow `the seven rules of a great git commit message`_.
+- Make sure your commit messages follow `the seven rules of a great git commit message`_:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
@@ -119,7 +123,7 @@ Writing documentation, function docstrings, examples and tutorials is a great wa
The documentation is written in `reStructuredText`_, with `Sphinx`_ used to generate these lovely HTML files that you're currently reading (unless you're reading this on GitHub). You can edit the documentation using any text editor and then generate the HTML output by running `make html` in the ``docs/`` directory.
-The function docstrings are written using the `numpydoc`_ extension for Sphinx. Make sure you check out how its format guidelines, before you start writing one.
+The function docstrings are written using the `numpydoc`_ extension for Sphinx. Make sure you check out how its format guidelines before you start writing one.
.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
.. _Sphinx: http://www.sphinx-doc.org/en/master/
@@ -128,14 +132,14 @@ The function docstrings are written using the `numpydoc`_ extension for Sphinx.
Filing Issues
-------------
-We use `GitHub issues`_ to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), it is advisable to use GitHub search to look for existing issues (both open and closed) that may be similar.
+We use `GitHub issues`_ to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), please use GitHub search to look for existing issues (both open and closed) that may be similar.
.. _GitHub issues: https://docs.pytest.org/en/latest/
Questions
^^^^^^^^^
-Please don't use GitHub issues for support questions, a better place for them would be `Stack Overflow`_. Make sure you tag them using the ``python-camelot`` tag.
+Please don't use GitHub issues for support questions. A better place for them would be `Stack Overflow`_. Make sure you tag them using the ``python-camelot`` tag.
.. _Stack Overflow: http://stackoverflow.com
diff --git a/docs/index.rst b/docs/index.rst
index 00605e41..e2d5857b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -23,11 +23,11 @@ Release v\ |version|. (:ref:`Installation `)
.. image:: https://img.shields.io/pypi/pyversions/camelot-py.svg
:target: https://pypi.org/project/camelot-py/
-**Camelot** is a Python library which makes it easy for *anyone* to extract tables from PDF files!
+**Camelot** is a Python library that makes it easy for *anyone* to extract tables from PDF files!
----
-**Here's how you can extract tables from PDF files.** Check out the PDF used in this example, `here`_.
+**Here's how you can extract tables from PDF files.** Check out the PDF used in this example `here`_.
.. _here: _static/pdf/foo.pdf
@@ -55,15 +55,15 @@ Release v\ |version|. (:ref:`Installation `)
There's a :ref:`command-line interface ` too!
-.. note:: Camelot only works with text-based PDFs and not scanned documents. If you can click-and-drag to select text in your table in a PDF viewer, then your PDF is text-based.
+.. note:: Camelot only works with text-based PDFs and not scanned documents. If you can click and drag to select text in your table in a PDF viewer, then your PDF is text-based.
Why Camelot?
------------
-- **You are in control**: Unlike other libraries and tools which either give a nice output or fail miserably (with no in-between), Camelot gives you the power to tweak table extraction. (Since everything in the real world, including PDF table extraction, is fuzzy.)
-- **Metrics**: *Bad* tables can be discarded based on metrics like accuracy and whitespace, without ever having to manually look at each table.
-- Each table is a **pandas DataFrame**, which enables seamless integration into `ETL and data analysis workflows`_.
-- **Export** to multiple formats, including json, excel and html.
+- **You are in control.** Unlike other libraries and tools which either give a nice output or fail miserably (with no in-between), Camelot gives you the power to tweak table extraction. (This is important since everything in the real world, including PDF table extraction, is fuzzy.)
+- *Bad* tables can be discarded based on **metrics** like accuracy and whitespace, without ever having to manually look at each table.
+- Each table is a **pandas DataFrame**, which seamlessly integrates into `ETL and data analysis workflows`_.
+- **Export** to multiple formats, including JSON, Excel and HTML.
See `comparison with other PDF table extraction libraries and tools`_.
@@ -73,7 +73,7 @@ See `comparison with other PDF table extraction libraries and tools`_.
The User Guide
--------------
-This part of the documentation, begins with some background information about why Camelot was created, takes a small dip into the implementation details and then focuses on step-by-step instructions for getting the most out of Camelot.
+This part of the documentation begins with some background information about why Camelot was created, takes a small dip into the implementation details and then focuses on step-by-step instructions for getting the most out of Camelot.
.. toctree::
:maxdepth: 2
@@ -85,8 +85,8 @@ This part of the documentation, begins with some background information about wh
user/advanced
user/cli
-The API Documentation / Guide
------------------------------
+The API Documentation/Guide
+---------------------------
If you are looking for information on a specific function, class, or method,
this part of the documentation is for you.
diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index e73d3e43..fd65005a 100644
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -8,7 +8,7 @@ This page covers some of the more advanced configurations for :ref:`Lattice ` needs the lines that make the table, to be in foreground. Here's an example of a table with lines in background.
+To detect line segments, :ref:`Lattice ` needs the lines that make the table to be in the foreground. Here's an example of a table with lines in the background:
.. figure:: ../_static/png/background_lines.png
:scale: 50%
@@ -68,16 +68,16 @@ Let's plot all the text present on the table's PDF page.
:alt: A plot of all text on a PDF page
:align: left
-This, as we shall later see, is very helpful with :ref:`Stream `, for noting table areas and column separators, in case Stream does not guess them correctly.
+This, as we shall later see, is very helpful with :ref:`Stream ` for noting table areas and column separators, in case Stream does not guess them correctly.
-.. note:: The *x-y* coordinates shown aboe change as you move your mouse cursor on the image, which can help you note coordinates.
+.. note:: The *x-y* coordinates shown above change as you move your mouse cursor on the image, which can help you note coordinates.
.. _geometry_table:
table
^^^^^
-Let's plot the table (to see if it was detected correctly or not). This geometry type, along with contour, line and joint is useful for debugging and improving the extraction output, in case the table wasn't detected correctly. More on that later.
+Let's plot the table (to see if it was detected correctly or not). This geometry type, along with contour, line and joint is useful for debugging and improving the extraction output, in case the table wasn't detected correctly. (More on that later.)
::
@@ -170,9 +170,9 @@ In cases like `these <../_static/pdf/column_separators.pdf>`__, where the text i
You can pass the column separators as a list of comma-separated strings to :meth:`read_pdf() `, using the ``columns`` keyword argument.
-In case you passed a single column separators string list, and no table area is specified, the separators will be applied to the whole page. When a list of table areas is specified and there is a need to specify column separators as well, **the length of both lists should be equal**. Each table area will be mapped to each column separators' string using their indices.
+In case you passed a single column separators string list, and no table area is specified, the separators will be applied to the whole page. When a list of table areas is specified and you need to specify column separators as well, **the length of both lists should be equal**. Each table area will be mapped to each column separators' string using their indices.
-For example, if you have specified two table areas, ``table_areas=['12,23,43,54', '20,33,55,67']``, and only want to specify column separators for the first table, you can pass an empty string for the second table in the column separators' list, like this, ``columns=['10,120,200,400', '']``.
+For example, if you have specified two table areas, ``table_areas=['12,23,43,54', '20,33,55,67']``, and only want to specify column separators for the first table, you can pass an empty string for the second table in the column separators' list like this, ``columns=['10,120,200,400', '']``.
Let's get back to the *x* coordinates we got from :ref:`plotting text ` that exists on this `PDF <../_static/pdf/column_separators.pdf>`__, and get the table out!
@@ -188,12 +188,12 @@ Let's get back to the *x* coordinates we got from :ref:`plotting text `_ merged the strings, "NUMBER", "TYPE" and "DBA NAME"; all of them were assigned to the same cell. Let's see how we can fix this in the next section.
+Ah! Since `PDFMiner `_ merged the strings, "NUMBER", "TYPE" and "DBA NAME", all of them were assigned to the same cell. Let's see how we can fix this in the next section.
Split text along separators
---------------------------
-To deal with cases like the output from the previous section, you can pass ``split_text=True`` to :meth:`read_pdf() `, which will split any strings that lie in different cells but have been assigned to the a single cell (as a result of being merged together by `PDFMiner `_).
+To deal with cases like the output from the previous section, you can pass ``split_text=True`` to :meth:`read_pdf() `, which will split any strings that lie in different cells but have been assigned to a single cell (as a result of being merged together by `PDFMiner `_).
::
@@ -210,13 +210,13 @@ To deal with cases like the output from the previous section, you can pass ``spl
Flag superscripts and subscripts
--------------------------------
-There might be cases where you want to differentiate between the text, and superscripts or subscripts, like this `PDF <../_static/pdf/superscript.pdf>`_.
+There might be cases where you want to differentiate between the text and superscripts or subscripts, like this `PDF <../_static/pdf/superscript.pdf>`_.
.. figure:: ../_static/png/superscript.png
:alt: A PDF with superscripts
:align: left
-In this case, the text that `other tools`_ return, will be ``24.912``. This is harmless as long as there is that decimal point involved. But when it isn't there, you'll be left wondering why the results of your data analysis were 10x bigger!
+In this case, the text that `other tools`_ return, will be ``24.912``. This is relatively harmless when that decimal point is involved. But when it isn't there, you'll be left wondering why the results of your data analysis are 10x bigger!
You can solve this by passing ``flag_size=True``, which will enclose the superscripts and subscripts with ``