docs: Cleanup docs with modern python examples (#1301)

README.rst

@@ -2,7 +2,7 @@
 splinter
 ++++++++
 
-Splinter is a Python framework that provides a simple and consistent interface for web application automation.
+Splinter is a simple and consistent API for web application automation.
 
 .. |pypi| image:: https://img.shields.io/pypi/v/splinter.svg
   :target: https://pypi.org/project/splinter

docs/index.rst

@@ -12,9 +12,9 @@
   :caption: Overview
   :hidden:
 
-  why
-  changelog
-  tutorial
+  overview/why
+  overview/changelog
+  overview/tutorial
 
 .. toctree::
   :caption: Installation Guide

docs/install/driver_install.rst

@@ -6,74 +6,65 @@
     :description: How to use splinter with Chrome WebDriver
     :keywords: splinter, python, tutorial, how to install, installation, chrome, selenium
 
-+++++++
-Drivers
-+++++++
++++++++++++++++
+Install Drivers
++++++++++++++++
+.. _install-drivers:
 
+The various Drivers which are supported by splinter must be installed separately.
 
-Selenium-based Drivers
-======================
+Install Using Extra Arguments
+=============================
 
-To use ``chrome``, ``fireFox``, ``edge``, or ``remote``, the python bindings for Selenium must be installed.
+When splinter is installed via pip, extra arguments can be provided.
+These will automatically install the latest version of the desired driver.
 
-When splinter is installed via pip, the `selenium` extra argument can be provided.
-This will automatically install the latest version of Selenium.
+The following are the valid extra arguments
 
+- selenium
+- django
+- flask
+- zope.testbrowser
+
+Example
+-------
+
+To install splinter with selenium included automatically:
 
 .. code-block:: bash
 
-    python -m pip install splinter[selenium]
+    pip install splinter[selenium]
+
 
+Selenium
+========
 
+To use ``chrome``, ``fireFox``, ``edge``, or ``remote``, the
+`python bindings for Selenium <https://pypi.org/project/selenium/>`_ must be installed.
 
 Django
 ======
 
 To use the ``django``, the following must be installed:
 
-`django <http://pypi.python.org/pypi/django>`_,
-`lxml <https://pypi.python.org/pypi/lxml>`_,
-`cssselect <http://pypi.python.org/pypi/cssselect>`_.
-
-When splinter is installed via pip, the `django` extra argument can be provided.
-This will automatically install Django.
-
-.. code-block:: bash
-
-    python -m pip install splinter[django]
-
+- `django <http://pypi.python.org/pypi/django>`_
+- `lxml <https://pypi.python.org/pypi/lxml>`_
+- `cssselect <http://pypi.python.org/pypi/cssselect>`_
 
 Flask
 =====
 
-
 To use the ``flask`` driver, the following must be installed:
 
-`Flask <https://pypi.python.org/pypi/Flask>`_,
-`lxml <https://pypi.python.org/pypi/lxml>`_,
-`cssselect <http://pypi.python.org/pypi/cssselect>`_.
-
-When splinter is installed via pip, the `flask` extra argument can be provided.
-This will automatically install Flask.
-
-.. code-block:: bash
-
-    python -m pip install splinter[flask]
-
+- `Flask <https://pypi.python.org/pypi/Flask>`_
+- `lxml <https://pypi.python.org/pypi/lxml>`_
+- `cssselect <http://pypi.python.org/pypi/cssselect>`_
 
 zope.testbrowser
 ================
 
-
 To use the ``zope.testbrowser``, the following must be installed:
 
-`zope.testbrowser <http://pypi.python.org/pypi/zope.testbrowser>`_,
-`lxml <https://pypi.python.org/pypi/lxml>`_,
-`cssselect <http://pypi.python.org/pypi/cssselect>`_.
-
-When splinter is installed via pip, the `zope.testbrowser` extra argument can be provided.
-This will automatically install Flask.
-
-.. code-block:: bash
-
-    python -m pip install splinter[zope.testbrowser]
+- `zope.testbrowser <http://pypi.python.org/pypi/zope.testbrowser>`_
+- `lxml <https://pypi.python.org/pypi/lxml>`_
+- `cssselect <http://pypi.python.org/pypi/cssselect>`_

docs/install/external.rst

@@ -9,8 +9,8 @@ Chrome
 
 The following applications are required:
 
-  - `Google Chrome <http://google.com/chrome>`_
-  - `ChromeDriver <https://chromedriver.chromium.org/>`_
+- `Google Chrome <http://google.com/chrome>`_
+- `ChromeDriver <https://chromedriver.chromium.org/>`_
 
 Chromedriver must also be available on your operating system's `PATH` environment variable.
 
@@ -70,8 +70,8 @@ Firefox
 
 The following applications are required:
 
-  - `Mozilla Firefox <http://firefox.com>`_
-  - `Geckodriver <https://github.com/mozilla/geckodriver/releases>`_
+- `Mozilla Firefox <http://firefox.com>`_
+- `Geckodriver <https://github.com/mozilla/geckodriver/releases>`_
 
 Geckodriver must also be available on your operating system's `PATH` environment variable.
 
@@ -95,8 +95,8 @@ Edge
 
 The following applications are required:
 
-  - `Microsoft Edge <https://www.microsoft.com/edge>`_
-  - `Microsoft Edge Driver <https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/>`_
+- `Microsoft Edge <https://www.microsoft.com/edge>`_
+- `Microsoft Edge Driver <https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/>`_
 
 Microsoft Edge Driver must also be available on your operating system's `PATH` environment variable.
 

docs/install/install.rst

@@ -15,28 +15,28 @@ Basic Requirements
 
 Splinter officially supports Python versions 3.8 and up.
 
-Latest version via pip
-======================
+pip
+===
 
 To install the latest release, run the following command in the terminal:
 
 .. code-block:: bash
 
-	   python -m pip install splinter
+	   pip install splinter
 
 
 Install With Driver Dependencies
 --------------------------------
 
 pip can be given extra arguments to automatically install driver dependencies.
 
-The `Install Drivers` section of the documentation has more information for each driver.
+The :ref:`Install Drivers <install-drivers>` section of the documentation has more information for each driver.
 
 .. highlight:: bash
 
 ::
 
-  $ python -m pip install splinter[django]
+  $ pip install splinter[selenium]
 
 
 From Source Code
@@ -59,4 +59,4 @@ Once you have a copy of the source code, you can manually install the package:
 ::
 
     $ cd splinter
-    $ python setup.py install
+    $ pip install .

docs/changelog.rst → docs/overview/changelog.rst

@@ -6,4 +6,4 @@
 Changelog
 +++++++++
 
-.. include:: ../CHANGELOG.rst
+.. include:: ../../CHANGELOG.rst

docs/tutorial.rst → docs/overview/tutorial.rst

@@ -10,7 +10,7 @@
 Tutorial
 ++++++++
 
-Before starting, make sure Splinter is :doc:`installed <install/install>`
+Before starting, make sure Splinter is :doc:`installed <../install/install>`
 
 This tutorial provides a simple example, teaching step by step how to:
 

docs/why.rst → docs/overview/why.rst

@@ -2,8 +2,7 @@
 Why Use Splinter?
 +++++++++++++++++
 
-
-Splinter is used to write web browser automation scripts.
+Splinter is a Python library used to write web browser automation scripts.
 
 The project has two primary goals: