docs: add the start of a contributor's guidejlvillal/devel_docs

Create an initial contributor's guide that will hopefully be expanded
on in the future.

1 files changed, 92 insertions, 0 deletions

diff --git a/docs/contributor/dev-quickstart.rst b/docs/contributor/dev-quickstart.rst
new file mode 100644
index 0000000..9733560
--- /dev/null
+++ b/docs/contributor/dev-quickstart.rst
@@ -0,0 +1,92 @@
+.. _dev-quickstart:
+
+=====================
+Developer Quick-Start
+=====================
+
+This is a quick walkthrough to get you started developing code for
+python-gitlab.  This assumes you are already familiar with submitting code
+reviews to a Github based project.
+
+The CI (Continuous Integration) system currently runs the unit tests under
+Python 3.7, 3.8, 3.9, and 3.10. It is strongly encouraged to run the unit tests
+locally prior to submitting a patch.
+
+Prepare Development System
+==========================
+
+System Prerequisites
+--------------------
+
+The following packages cover the prerequisites for a local development
+environment on most current distributions. Instructions for getting set up with
+non-default versions of Python and on older distributions are included below as
+well.
+
+- Ubuntu/Debian::
+
+    sudo apt-get install python3-pip git
+
+- RHEL/CentOS/Fedora::
+
+    sudo dnf install python3-pip git
+
+Python Prerequisites
+--------------------
+
+We suggest to use at least tox 3.24, if your distribution has an older version,
+you can install it using pip system-wise or better per user using the --user
+option that by default will install the binary under $HOME/.local/bin, so you
+need to be sure to have that path in $PATH; for example::
+
+    pip3 install tox --user
+
+will install tox as ~/.local/bin/tox
+
+You may need to explicitly upgrade virtualenv if you've installed the one
+from your OS distribution and it is too old (tox will complain). You can
+upgrade it individually, if you need to::
+
+    pip3 install -U virtualenv --user
+
+Running Unit Tests Locally
+==========================
+
+If you haven't already, python-gitlab source code should be pulled directly from git::
+
+    # from your home or source directory
+    cd ~
+    git clone https://github.com/python-gitlab/python-gitlab
+    cd python-gitlab
+
+Running Unit and Style Tests
+----------------------------
+
+All unit tests should be run using tox. To run python-gitlab's entire test suite::
+
+    # to run the py3 unit tests, and the style tests
+    tox
+
+To run a specific test or tests, use the "-e" option followed by the tox target
+name. For example::
+
+    # run the unit tests under py310 (Python 3.10) and also run the pep8 tests
+    tox -e py310,pep8
+
+You may pass options to the test programs using positional arguments.
+To run a specific unit test, this passes the desired test
+(regex string) to `pytest <https://docs.pytest.org/en/latest/>`_::
+
+    # run tests for Python 3.8 which match the string 'test_projects'
+    tox -e py310 -- -k test_projects
+
+Additional Tox Targets
+----------------------
+
+There are several additional tox targets not included in the default list, such
+as the target which builds the documentation site.   See the ``tox.ini`` file
+for a complete listing of tox targets. These can be run directly by specifying
+the target name::
+
+    # generate the documentation pages locally
+    tox -e docs