[py] Update instructions for docs

Author: cgoldberg

py/docs/README.rst

@@ -11,52 +11,56 @@ How to build docs
 =================
 
 One can build the Python documentation without doing a full bazel build. The
-following instructions will build the setup a virtual environment and installs tox, clones the
-selenium repo and then runs ``tox -c py/tox.ini`` building the Python documentation.
+following instructions will build the setup a virtual environment and installs tox,
+clones the selenium repo and then runs ``tox -c py/tox.ini`` building the Python documentation.
 
 .. code-block:: console
 
-    virtualenv test-py38-env
-    source test-py38-env/bin/activate
+    python3 -m venv
+    source venv/bin/activate
     pip install tox
     git clone [email protected]:SeleniumHQ/selenium.git
     cd selenium/
     # uncomment and switch to your development branch if needed 
     #git switch -c feature-branch origin/feature-branch
     tox -c py/tox.ini
 
-Works in similar manner as the larger selenium bazel doing just the python documentation portion.
+This works in a similar manner as the larger selenium bazel build, but does just the Python
+documentation portion.
 
 What is happening under the covers of tox, sphinx
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-tox is essentially a build tool for Python. Here it setups its own virtualenv and installs the
-documentation packages (sphinx and jinja2) as well as the required selenium python
-dependencies. Then tox runs the sphinx generate autodoc stub files and then builds the docs.
+tox is essentially a build tool for Python. Here it sets up its own virtual env and installs
+the documentation packages (sphinx and jinja2) as well as the required selenium python
+dependencies. Then tox runs the ``sphinx-autogen`` command to generate autodoc stub pages.
+Then it runs ``sphinx-build`` to build the HTML docs.
 
 Sphinx is .. well a much larger topic then what we could cover here. Most important to say
-here is that the docs are using the "classic" theme and than the majority of the api documentation
-is autogenerated. There is plenty of information available and currently the documentation is
-fairly small and not complex. So some basic understanding of restructed text and the Sphinx tool chain
-should be sufficient to contribute and develop the Python docs.
+here is that the docs are using the "sphinx_rtd_theme" theme (AKA "Read the Docs" theme) and
+the the majority of the api documentation is autogenerated. There is plenty of information
+available and currently the documentation is fairly small and not complex. So some basic
+understanding of reStructuredText and the Sphinx tool chain should be sufficient to contribute
+and develop the Python docs.
 
 To clean up the build / tox cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Although there is a Sphinx Makefile option to clean up using the tox environment above one can
-manually clean the build by deleting the build directory on the root (selenium/build using the
-default directory on git clone). Noting that both Sphinx and tox cache parts of their build and
-recognize changes to speed up their respective builds. But at times one wants to start fresh
-deleting the aformentioned directory will clean the Sphinx cache or removing selenium/py/.tox 
-directory for cleaning the tox environment.
+Although there is a Sphinx Makefile option to clean up using the tox environment above, one can
+manually clean the build by deleting the build directory on the root (``selenium/build`` using the
+default directory on git clone). Note that both Sphinx and tox cache parts of their build and
+recognize changes to speed up their respective builds. To start fresh, delete the aformentioned
+directory to clean the Sphinx cache and delete the ``selenium/py/.tox`` directory to clean the
+tox environment.
 
 
 Known documentation issues
 ==========================
 The API Reference primarily builds from the source code. But currently the initial template stating
-which modules to document is hard coded within py/docs/source/api.rst. So if modules are added or
-removed then the generated docs will be inaccurate. It would be preferred that the API docs generate
-soley from the code if possible. This is being tracked in `#14178 <https://github.com/SeleniumHQ/selenium/issues/14178>`_
+which modules to document is hard coded within ``py/docs/source/api.rst``. So if modules are added or
+removed, then the generated docs will be inaccurate. It would be preferred that the API docs generate
+soley from the code if possible. This is being tracked in
+`#14178 <https://github.com/SeleniumHQ/selenium/issues/14178>`_
 
-We are working through the Sphinx build Warnings and Errors trying to clean up botht the syntax and
+We are working through the Sphinx build warnings and errors, trying to clean up both the syntax and
 the build.
 
 Contributing to Python docs
@@ -65,7 +69,7 @@ First it is recommended that you read the main `CONTRIBUTING.md <https://github.
 
 Some steps for contibuting to the Python documentation ..
 
-- Check out changes locally using instruction above.
-- Try to resolve any warnings/issues.
-  - If too arduous either ask for help or add to list of known issue.
-- If this process is updated please update this doc as well to help the next person.
+- Check out changes locally using instructions above.
+- Try to resolve any warnings/errors.
+  - If too arduous, either ask for help or add to the list of known issues.
+- If this process is updated, please update this doc as well to help the next person.