From 931da93595e14ebc942a808bb1ba1e62e0621a3c Mon Sep 17 00:00:00 2001 From: jsfehler Date: Fri, 21 Jun 2024 18:15:04 -0400 Subject: [PATCH] docs: Cleanup docs with modern python examples (#1301) --- README.rst | 2 +- docs/_static/splinter-docs.css | 81 ------------------------------- docs/index.rst | 6 +-- docs/install/driver_install.rst | 77 +++++++++++++---------------- docs/install/external.rst | 12 ++--- docs/install/install.rst | 12 ++--- docs/{ => overview}/changelog.rst | 2 +- docs/{ => overview}/tutorial.rst | 2 +- docs/{ => overview}/why.rst | 3 +- 9 files changed, 53 insertions(+), 144 deletions(-) delete mode 100644 docs/_static/splinter-docs.css rename docs/{ => overview}/changelog.rst (83%) rename docs/{ => overview}/tutorial.rst (98%) rename docs/{ => overview}/why.rst (96%) diff --git a/README.rst b/README.rst index 7b512c094..e6093e2c0 100644 --- a/README.rst +++ b/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 diff --git a/docs/_static/splinter-docs.css b/docs/_static/splinter-docs.css deleted file mode 100644 index e1d582f53..000000000 --- a/docs/_static/splinter-docs.css +++ /dev/null @@ -1,81 +0,0 @@ -#main ul.simple { - font-size: 95%; - margin: 20px 0 20px 20px; -} - -#main ul.simple li { - display: block; - margin: 5px 0; -} - -.footer { - clear: both; -} - -body { - background: #FFF; - color: #000; -} - -.section blockquote div { - -webkit-border-radius: 4px; - -moz-border-radius: 4px - border-radius: 4px; - background-color: #EEEEEE; - margin-left: 40px; - width: 590px; - padding: 10px; -} - -div.document { - background-color: #FFF; -} - -div.highlight pre { - -khtml-border-radius: 5px; - -moz-border-radius: 5px; - -ms-border-radius: 5px; - -o-border-radius: 5px; - -webkit-border-radius: 5px; - border-radius: 5px; - padding: 5px; -} - -div.highlight-bash { - margin: 20px; -} - -div.highlight { - margin: 20px; -} - -div.highlight-python pre { - -khtml-border-radius: 5px; - -moz-border-radius: 5px; - -ms-border-radius: 5px; - -o-border-radius: 5px; - -webkit-border-radius: 5px; - border-radius: 5px; - padding: 5px; -} - -div.toctree-wrapper { - line-height: 22px; - margin-left: 24px; -} - -div.toctree-wrapper ul li { - list-style: disc inside; -} - -strong { - font-weight: bold; -} - -em { - font-style: italic; -} - -a > em { - font-style: normal; -} diff --git a/docs/index.rst b/docs/index.rst index 1b3a33806..30c857991 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,9 +12,9 @@ :caption: Overview :hidden: - why - changelog - tutorial + overview/why + overview/changelog + overview/tutorial .. toctree:: :caption: Installation Guide diff --git a/docs/install/driver_install.rst b/docs/install/driver_install.rst index 943f33cb2..53526214a 100644 --- a/docs/install/driver_install.rst +++ b/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 `_ must be installed. Django ====== To use the ``django``, the following must be installed: -`django `_, -`lxml `_, -`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 `_ +- `lxml `_ +- `cssselect `_ Flask ===== - To use the ``flask`` driver, the following must be installed: -`Flask `_, -`lxml `_, -`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 `_ +- `lxml `_ +- `cssselect `_ zope.testbrowser ================ - To use the ``zope.testbrowser``, the following must be installed: -`zope.testbrowser `_, -`lxml `_, -`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 `_ +- `lxml `_ +- `cssselect `_ diff --git a/docs/install/external.rst b/docs/install/external.rst index 7f6998a08..db4e16d71 100644 --- a/docs/install/external.rst +++ b/docs/install/external.rst @@ -9,8 +9,8 @@ Chrome The following applications are required: - - `Google Chrome `_ - - `ChromeDriver `_ +- `Google Chrome `_ +- `ChromeDriver `_ 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 `_ - - `Geckodriver `_ +- `Mozilla Firefox `_ +- `Geckodriver `_ 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 `_ - - `Microsoft Edge Driver `_ +- `Microsoft Edge `_ +- `Microsoft Edge Driver `_ Microsoft Edge Driver must also be available on your operating system's `PATH` environment variable. diff --git a/docs/install/install.rst b/docs/install/install.rst index 2e6c38684..2a146469f 100644 --- a/docs/install/install.rst +++ b/docs/install/install.rst @@ -15,14 +15,14 @@ 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 @@ -30,13 +30,13 @@ 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 ` 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 . diff --git a/docs/changelog.rst b/docs/overview/changelog.rst similarity index 83% rename from docs/changelog.rst rename to docs/overview/changelog.rst index 53aa5e798..3cb1c3a51 100644 --- a/docs/changelog.rst +++ b/docs/overview/changelog.rst @@ -6,4 +6,4 @@ Changelog +++++++++ -.. include:: ../CHANGELOG.rst +.. include:: ../../CHANGELOG.rst diff --git a/docs/tutorial.rst b/docs/overview/tutorial.rst similarity index 98% rename from docs/tutorial.rst rename to docs/overview/tutorial.rst index a1702f0ff..525a0afe6 100644 --- a/docs/tutorial.rst +++ b/docs/overview/tutorial.rst @@ -10,7 +10,7 @@ Tutorial ++++++++ -Before starting, make sure Splinter is :doc:`installed ` +Before starting, make sure Splinter is :doc:`installed <../install/install>` This tutorial provides a simple example, teaching step by step how to: diff --git a/docs/why.rst b/docs/overview/why.rst similarity index 96% rename from docs/why.rst rename to docs/overview/why.rst index edf651664..9457baa1e 100644 --- a/docs/why.rst +++ b/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: