diff --git a/docs/contribute/contribute.rst b/docs/contribute/contribute.rst index 7dfc5ad44..49ac7b7a5 100644 --- a/docs/contribute/contribute.rst +++ b/docs/contribute/contribute.rst @@ -10,7 +10,7 @@ Contributing ++++++++++++ -The Source Code is hosted on `GitHub `_ +The Source Code is hosted on `GitHub `_. For small fixes, opening a new Pull Request in the project's repo is fine. @@ -23,26 +23,32 @@ Before opening a new Pull Request, please ensure the linter and at least platfor Requirements ============ -Development environments are managed using `tox `_ +Development environments are managed using `tox `_. Generally, tox should be installed with pip: -.. highlight:: bash - -:: +.. code-block:: bash pip install tox See tox's documentation if you need to use another method. + +tox can then be run from the project root: + + +.. code-block:: bash + + cd /path/to/source_code + # Lists the possible environments to use with `tox -e` + tox l + Linter ====== Splinter enforces code standards using various linting tools. They can be run from tox: -.. highlight:: bash - -:: +.. code-block:: bash tox -e lint @@ -54,35 +60,35 @@ Tests Run --- -The tests are split into two groups: Platform agnostic and Windows-only. +The tests are split into groups: Platform agnostic, Windows-only, and macOS-only. To run the platform agnostic tests: -.. highlight:: bash - -:: +.. code-block:: bash tox -e tests -- tests/ - tox -e tests_selenium4 -- tests/ + tox -e tests_selenium -- tests/ -To run the windows tests: +To run the Windows tests: -.. highlight:: bash +.. code-block:: bash -:: + tox -e tests_windows_selenium -- tests/ - tox -e tests_windows -- tests/ - tox -e tests_windows_selenium4 -- tests/ +To run the macOS tests: -You can also specify one or more test files to run: +.. code-block:: bash + + tox -e tests_macos_selenium -- tests/ -.. highlight:: bash -:: +You can also specify one or more test files to run: + +.. code-block:: bash - $ tox -e tests_windows_selenium4 -- tests/test_webdriver_firefox.py, tests/test_request_handler.py + tox -e tests_windows_selenium -- tests/test_webdriver_firefox.py, tests/test_request_handler.py Documentation @@ -91,10 +97,10 @@ Documentation Write ----- -Documentation is written using `Sphinx `_, +Documentation is written using `Sphinx `_, which uses `RST `_. -We use the `Read the Docs Sphinx Theme `_. +We use the `Sphinx-Immaterial Theme `_. Build @@ -103,11 +109,13 @@ Build The `build_docs` environment is a wrapper around Sphinx's Makefile. Arguments will be passed to the Makefile. Thus, to build the docs in HTML format: -.. highlight:: bash +.. code-block:: bash + + tox -e build_docs -- html -:: - tox -e build_docs html +The documentation will then be built inside the `docs/_build/html` directory: +.. code-block:: bash -The documentation will then be built inside the `docs/_build` directory. + open docs/_build/html/index.html diff --git a/docs/drivers/firefox.rst b/docs/drivers/firefox.rst index 6cbfd8fb0..94ea68cd3 100644 --- a/docs/drivers/firefox.rst +++ b/docs/drivers/firefox.rst @@ -66,7 +66,7 @@ For example: from selenium import webdriver firefox_options = webdriver.firefox.options.Options() - firefox_options.binary_location = "/path/to/canary" + firefox_options.binary_location = "/path/to/firefox_nightly" browser = Browser('firefox', options=firefox_options) diff --git a/docs/drivers/installing_pyqt.rst b/docs/drivers/installing_pyqt.rst deleted file mode 100644 index 018dcf23b..000000000 --- a/docs/drivers/installing_pyqt.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. Copyright 2012 splinter authors. All rights reserved. - Use of this source code is governed by a BSD-style - license that can be found in the LICENSE file. - -.. meta:: - :description: Learn how to install PyQt4 on your machine. - :keywords: splinter, python, cobrateam, pyqt, pyqt4 - -++++++++++++++++ -Installing PyQt4 -++++++++++++++++ - -In order to use Spynner driver, you need to install PyQt4. PyQt4 itself has a few dependencies; -follow the steps below to get PyQt4 and its dependencies running on your system. - -Install Qt4 -=========== - -The biggest and most important PyQt4 dependency is the Qt4 itself. -You can download it from its `official website `_ and -install with a nice and friendly wizard. - -Install SIP -=========== - -Another PyQt4 dependency is `SIP `_, which -is a tool used to create Python bindings for C and C++ libraries. You can navigate to the -`download page on SIP website `_, -choose the version according to your operating system, extract the download package and -install it using three commands: - -.. highlight:: bash - -:: - - $ tar -xvzf sip-4.xx.x.tar.gz - $ cd sip-4.xx.x - $ python configure.py - $ make - $ [sudo] make install - -Install PyQt4 -============= - -Now we can finally install PyQt4. Go to the `PyQt4 download page `_ -and download the PyQt4 version according to your platform. After these steps, all you need to do is extract the download -package and install PyQt4 using these commands: - -.. highlight:: bash - -:: - - $ tar -xvzf PyQt-plat-gpl-4.x.x.tar.gz - $ cd PyQt-plat-gpl-4.x.x - $ python configure.py --no-designer-plugin --qmake=/usr/bin/qmake-4.x # important, on Mac OS X don't use /usr/bin/qmake, specify the version! - $ make - $ [sudo] make install - -Now you PyQt4 installed on your system. Happy hacking :) - -For more information in specific platforms, check these links out: - - * `Installing PyQt on Mac OS X (Snow Leopard) `_ - * `Installing PyQt on Windows `_ - * `Installing PyQt on Linux (Ubuntu) `_ diff --git a/docs/news/0.03.0.rst b/docs/news/0.03.0.rst index e9099b109..c6f84b955 100644 --- a/docs/news/0.03.0.rst +++ b/docs/news/0.03.0.rst @@ -22,7 +22,7 @@ Features Documentation improvements -------------------------- -- complete :doc:`API reference ` +- complete API reference - instructions on :doc:`new drivers creation ` Backward incompatible changes diff --git a/docs/news/0.04.0.rst b/docs/news/0.04.0.rst index 213f7e600..d7afd0635 100644 --- a/docs/news/0.04.0.rst +++ b/docs/news/0.04.0.rst @@ -19,7 +19,7 @@ Features Documentation improvements -------------------------- -- improved :doc:`API docs ` +- improved API docs - added docs for ``is_text_present`` method - added API docs for ``is_element_present_by_*`` methods - added docs for :doc:`mouse interactions ` diff --git a/docs/selenium-keys.rst b/docs/selenium-keys.rst index 21c74e419..56fb2e979 100644 --- a/docs/selenium-keys.rst +++ b/docs/selenium-keys.rst @@ -12,16 +12,16 @@ Selenium Keys With Splinter's type() method, you can use Selenium's Keys implementation. -.. highlight:: python - -:: +.. code-block:: python from selenium.webdriver.common.keys import Keys from splinter import Browser browser = Browser() - browser.type(Keys.RETURN) + browser.visit("https://duckduckgo.com/") + browser.type("q", "selenium.webdriver.common.keys") + browser.type("q", Keys.ENTER) The full list of all supported keys can be found at the official Selenium documentation: `selenium.webdriver.common.keys `_ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 821f52acb..a1702f0ff 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -106,8 +106,8 @@ In order to find Google's search button, do: browser.visit('http://google.com') input_element = browser.find_by_name('q') input_element.fill('splinter - python acceptance testing for web applications') - - button_element = browser.find_by_name('btnK') + # There are two elements with name btnK - only the second is visible + button_element = browser.find_by_name('btnK')[1] **Note** The name ``btnK`` was found by inspecting Google's search page source code. @@ -125,8 +125,8 @@ With the button identified, we can then click it: browser.visit('http://google.com') input_element = browser.find_by_name('q') input_element.fill('splinter - python acceptance testing for web applications') - - button_element = browser.find_by_name('btnK') + # There are two elements with name btnK - only the second is visible + button_element = browser.find_by_name('btnK')[1] button_element.click() @@ -142,7 +142,7 @@ With the button identified, we can then click it: browser.visit('http://google.com') browser.find_by_name('q').fill('splinter - python acceptance testing for web applications') - browser.find_by_name('btnK').click() + browser.find_by_name('btnK')[1].click() Check for results @@ -161,8 +161,8 @@ After pressing the button, you can check if Splinter official website is among t browser.visit('http://google.com') input_element = browser.find_by_name('q') input_element.fill('splinter - python acceptance testing for web applications') - - button_element = browser.find_by_name('btnK') + # There are two elements with name btnK - only the second is visible + button_element = browser.find_by_name('btnK')[1] button_element.click() if browser.is_text_present('splinter.readthedocs.io'): @@ -189,8 +189,8 @@ When you've finished testing, close your browser using ``browser.quit``: browser.visit('http://google.com') input_element = browser.find_by_name('q') input_element.fill('splinter - python acceptance testing for web applications') - - button_element = browser.find_by_name('btnK') + # There are two elements with name btnK - only the second is visible + button_element = browser.find_by_name('btnK')[1] button_element.click() if browser.is_text_present('splinter.readthedocs.io'): diff --git a/tox.ini b/tox.ini index c52252706..f0f5c085b 100644 --- a/tox.ini +++ b/tox.ini @@ -35,3 +35,11 @@ changedir = docs/ commands = make clean make {posargs} + +[testenv:lint] +skip_install = + true +deps = + pre-commit +commands = + pre-commit run --all-files --show-diff-on-failure