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.

4 files changed, 166 insertions, 0 deletions

diff --git a/docs/contributor/contributing.rst b/docs/contributor/contributing.rst
new file mode 100644
index 0000000..f4a165c
--- /dev/null
+++ b/docs/contributor/contributing.rst
@@ -0,0 +1,50 @@
+.. _code-contribution-guide:
+
+============================
+So You Want to Contribute...
+============================
+
+This document provides some necessary points for developers to consider when
+writing and reviewing python-gitlab code. The checklist will help developers get
+things right.
+
+Getting Started
+===============
+
+If you're completely new to GitHub development and want to contribute to the
+python-gitlab project, please start by familiarizing yourself with the `GitHub
+Getting Started Guide <https://docs.github.com/en/get-started>`_. This will
+help you familiarize yourself with the workflow for the GitHub continuous
+integration and testing systems, and help you with your first commit.
+
+Useful Links
+------------
+
+Bug/Task tracker
+    https://github.com/python-gitlab/python-gitlab/issues
+
+Code Hosting
+    https://github.com/python-gitlab/python-gitlab
+
+Getting Your Patch Merged
+-------------------------
+
+TODO: Document info that will be useful
+
+Bug Reporting
+=============
+
+Bugs can reported via our issue tracker at
+https://github.com/python-gitlab/python-gitlab/issues
+
+When filing bugs, please include as much detail as possible, and don't be shy.
+
+Essential pieces of information are generally:
+
+* Steps to reproduce the issue.
+* Exceptions and surrounding lines from the logs.
+* Versions of python-gitlab and Gitlab.
+
+Please also set your expectations of what *should* be happening.
+Statements of user expectations are how we understand what is occuring and
+how we learn new use cases!
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
diff --git a/docs/contributor/index.rst b/docs/contributor/index.rst
new file mode 100644
index 0000000..f8c6e12
--- /dev/null
+++ b/docs/contributor/index.rst
@@ -0,0 +1,23 @@
+.. python-gitlab documentation master file, created by
+   sphinx-quickstart on Mon Dec  8 15:17:39 2014.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Developer's Guide
+=================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   Developer Contribution Guide <contributing>
+   Setting Up Your Development Environment <dev-quickstart>
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/index.rst b/docs/index.rst
index 3f8672b..f5d600e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,7 @@ Contents:
    api-objects
    api/gitlab
    cli-objects
+   contributor/index
    changelog
    release-notes