Tidy up after reading contributing docs (#1255)

* Doc updates

Fixes some errors with build docs, some example code didn't run, general tidy up.

* Change is_current() to use the @Property decorator

* Add missing lint environment to tox.ini

* Revert changes to splinter/driver/webdriver/__init__.py

docs/contribute/contribute.rst

@@ -10,7 +10,7 @@
 Contributing
 ++++++++++++
 
-The Source Code is hosted on `GitHub <http://github.com/cobrateam/splinter>`_
+The Source Code is hosted on `GitHub <http://github.com/cobrateam/splinter>`_.
 
 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 <https://tox.wiki/en/latest/>`_
+Development environments are managed using `tox <https://tox.wiki/en/latest/>`_.
 
 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 <http://sphinx.pocoo.org/>`_,
+Documentation is written using `Sphinx <https://www.sphinx-doc.org/>`_,
 which uses `RST <http://docutils.sourceforge.net/rst.html>`_.
 
-We use the `Read the Docs Sphinx Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/index.html>`_.
+We use the `Sphinx-Immaterial Theme <https://jbms.github.io/sphinx-immaterial/>`_.
 
 
 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

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)
 
 

docs/news/0.03.0.rst

@@ -22,7 +22,7 @@ Features
 Documentation improvements
 --------------------------
 
-- complete :doc:`API reference </api/index>`
+- complete API reference
 - instructions on :doc:`new drivers creation </contribute/writing-new-drivers>`
 
 Backward incompatible changes

docs/news/0.04.0.rst

@@ -19,7 +19,7 @@ Features
 Documentation improvements
 --------------------------
 
-- improved :doc:`API docs </api/index>`
+- 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 </mouse-interaction>`

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 <https://seleniumhq.github.io/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html>`_

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'):

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