diff --git a/docs/contribute/contribute.rst b/docs/contribute/contribute.rst deleted file mode 100644 index 49ac7b7a5..000000000 --- a/docs/contribute/contribute.rst +++ /dev/null @@ -1,121 +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: Find how to contribute to splinter. - :keywords: splinter, python, contribution, open source, testing, web application - -++++++++++++ -Contributing -++++++++++++ - -The Source Code is hosted on `GitHub `_. - -For small fixes, opening a new Pull Request in the project's repo is fine. - -For larger issues or new features, please open an `issue `_ first. - -If you want to add a new driver, check out our :doc:`docs for creating new splinter drivers `. - -Before opening a new Pull Request, please ensure the linter and at least platform agnostic tests are passing on your branch. - -Requirements -============ - -Development environments are managed using `tox `_. - -Generally, tox should be installed with pip: - -.. 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: - -.. code-block:: bash - - tox -e lint - - -Tests -===== - - -Run ---- - -The tests are split into groups: Platform agnostic, Windows-only, and macOS-only. - -To run the platform agnostic tests: - -.. code-block:: bash - - tox -e tests -- tests/ - tox -e tests_selenium -- tests/ - - -To run the Windows tests: - -.. code-block:: bash - - tox -e tests_windows_selenium -- tests/ - - -To run the macOS tests: - -.. code-block:: bash - - tox -e tests_macos_selenium -- tests/ - - -You can also specify one or more test files to run: - -.. code-block:: bash - - tox -e tests_windows_selenium -- tests/test_webdriver_firefox.py, tests/test_request_handler.py - - -Documentation -============= - -Write ------ - -Documentation is written using `Sphinx `_, -which uses `RST `_. - -We use the `Sphinx-Immaterial Theme `_. - - -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: - -.. code-block:: bash - - tox -e build_docs -- html - - -The documentation will then be built inside the `docs/_build/html` directory: - -.. code-block:: bash - - open docs/_build/html/index.html diff --git a/docs/contribute/development-environment-setup.rst b/docs/contribute/development-environment-setup.rst deleted file mode 100644 index b74f47467..000000000 --- a/docs/contribute/development-environment-setup.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. Copyright © 2018 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: Setting up your development environment for Splinter. - :keywords: splinter, open source, python, contribute, development environment - -+++++++++++++++++++++++++++++ -Development Environment Setup -+++++++++++++++++++++++++++++ - -Setting up a splinter development environment is a really easy task. Once you have some -basic development tools on your machine, you can set up the entire environment with just one command. - -Basic Tools -=========== - -Let's deal with those tools first. - -macOS ------- - -If you're a macOS user, you just need to install Xcode, which can be downloaded -from Mac App Store (on Snow Leopard or later) or from -`Apple website `_. - -Linux ------ - -If you are running a Linux distribution, you need to install some basic development libraries -and headers. For example, on Ubuntu, you can easily install all of them using ``apt-get``: - -.. highlight:: bash - -:: - - $ [sudo] apt-get install build-essential python-dev libxml2-dev libxslt1-dev - -PIP and virtualenv ------------------- - -Make sure you have pip installed. We manage all splinter development dependencies with -`PIP `_, so you should use it too. - -And please, for the sake of a nice development environment, use `virtualenv `_. -If you aren't using it yet, start now. :) - -Dependencies ------------- - -Once you have all development libraries installed for your OS, just install all splinter development dependencies with -``make``: - -.. highlight:: bash - -:: - - $ [sudo] make dependencies - -**Note:** You will need ``sudo`` only if you aren't using virtualenv (which means you're a really bad guy - *no donuts for you*). - -Also make sure you have properly configured your :doc:`Chrome driver `. diff --git a/docs/contribute/development-environment.rst b/docs/contribute/development-environment.rst new file mode 100644 index 000000000..833d80ad4 --- /dev/null +++ b/docs/contribute/development-environment.rst @@ -0,0 +1,99 @@ +.. 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: Find how to contribute to splinter. + :keywords: splinter, python, contribution, open source, testing, web application + ++++++++++++++++++++++++ +Development Environment ++++++++++++++++++++++++ + +Setup +===== + +Splinter is written in Python 3. It targets active Python versions and generally drops support +for versions as they hit end of life status. For platform support, +we target Linux, MacOS, and Windows. + +Installing Python on your machine is out of scope for this documentation. + +We use `virtual environments `_ extensively +and manage them using `tox `_. + +Generally, tox should be installed with pip: + +.. 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 + + +Linting +======= + +Splinter enforces code standards using various linting tools. They can be run from tox: + +.. code-block:: bash + + tox -e lint + + +Testing +======= + +The following tox environments each run a subset of the test suite: + + - tests_splinter + - tests_lxml_drivers + - tests_selenium + - tests_selenium_remote + - tests_selenium_edge + - tests_selenium_safari + +Run +--- + +Running any suite is as simple as passing the environment name to tox: + +.. code-block:: bash + + tox -e tests_selenium + + +Documentation +============= + +Our documentation is written using `Sphinx `_, +which uses the `RST `_ format. + +For the documentation's visual theme, we use the `Sphinx-Immaterial Theme `_. + + +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: + +.. code-block:: bash + + tox -e build_docs -- html + + +The documentation will then be built inside the `docs/_build/html` directory: + +.. code-block:: bash + + open docs/_build/html/index.html diff --git a/docs/contribute/guidelines.rst b/docs/contribute/guidelines.rst new file mode 100644 index 000000000..2b9dec891 --- /dev/null +++ b/docs/contribute/guidelines.rst @@ -0,0 +1,20 @@ +.. Copyright 2024 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: Find how to contribute to splinter. + :keywords: splinter, python, contribution, open source, testing, web application + +++++++++++ +Guidelines +++++++++++ + +Splinter's source code is currently hosted on `GitHub `_. +All active development occurs inside this repository. + +For small changes such as documentation and bug fixes, it's fine to open a `Pull Request `_ with the changes. + +For larger issues such as new features, please open an `Issue `_ first. + +Before opening a new Pull Request, please ensure the linter and at least platform agnostic tests are passing on your branch. diff --git a/docs/index.rst b/docs/index.rst index ec801458b..3b37becd3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -79,6 +79,6 @@ :caption: Splinter Development :hidden: - contribute/development-environment-setup - contribute/contribute + contribute/guidelines + contribute/development-environment contribute/writing-new-drivers