Contributor's guide and getting started section content

docs/source/contribution/code_contribution.rst

@@ -0,0 +1,127 @@
+.. _contributing_documentation:
+
+=============================
+Contributing to the code base
+=============================
+
+.. contents:: Table of Contents:
+   :local:
+
+Opening an issue
+------------------
+
+GitHub Issues allows you to discuss and gather additional information concerning the problem you wish to undertake. 
+Before you work on any non-trivial code contribution, it is best to first create an issue in the `issue tracker <https://github.com/PolyPhyHub/PolyPhy/issues>`_  
+to start a discussion on the subject. 
+
+
+* Navigate to the main page of PolyPhy on GitHub.
+
+* Click Issues.
+
+* Click New issue.
+
+* Select the template according to the issue(if available) or open a blank issue.
+
+* Type a title and description for your issue.
+
+* When you're finished, click Submit a new issue.
+
+Creating a development environment
+-----------------------------------
+
+Before you start contributing, we recommend creating an isolated `virtual environment <https://realpython.com/python-virtual-environments-a-primer/>`_ to avoid any problems with your installed Python packages. 
+This can easily be done via either `virtualenv <https://virtualenv.pypa.io/en/stable/>`_::
+
+    virtualenv <PATH TO VENV>
+    source <PATH TO VENV>/bin/activate
+
+or `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_::
+
+    conda create -n polyphy python=3 six virtualenv pytest pytest-cov
+    conda activate polyphy
+
+Additionally, you can use `Tox <https://pypi.org/project/tox/3.1.2/>`_ to manage your virtual environment.
+Tox is a generic virtualenv management and test command line tool.
+
+Make sure to install tox in the root of your project. ::
+
+    tox # will download the dependencies you have specified, build the package, install it in a virtual environment and run the tests using pytest.
+    tox -e docs  # to build your documentation
+    tox -e build  # to build your package distribution
+    tox -e publish  # to test your project uploads correctly in test.pypi.org
+    tox -e publish -- --repository pypi  # to release your package to PyPI
+    tox -av  # to list all the tasks available
+
+Making a pull request
+-----------------------
+
+
+To submit pull requests, just head over to the PolyPhy repository on GitHub and click the “fork” button. After that, you need to clone the repository you forked using your favorite git client or git CLI.
+
+
+Creating a fork
+******************
+
+Clone your fork to your local machine::
+
+    git clone [email protected]:USERNAME/FORKED-PROJECT.git
+
+Keeping your fork up to date
+********************************
+
+Add 'upstream' repo to list of remotes::
+
+    git remote add upstream https://github.com/polyphy/polyphy.git
+
+Verify the new remote named 'upstream'::
+
+    git remote -v
+
+Fetch from upstream remote::
+
+    git fetch upstream
+
+View all branches, including those from upstream::
+
+    git branch -va
+
+Checkout your master branch and merge upstream::
+
+    git checkout master
+    git merge upstream/master
+
+Creating a branch
+**********************
+
+Checkout the master branch - you want your new branch to come from master::
+
+    git checkout master
+
+Create a new branch named newfeature or its own simple informative name::
+
+    git branch newfeature
+
+Switch to your new branch::
+
+    git checkout newfeature
+
+Now, you can make desired changes.
+
+Submitting a pull request
+******************************
+
+Fetch upstream master and merge with your repo's master branch::
+
+    git fetch upstream
+    git checkout master
+    git merge upstream/master
+
+If there were any new commits, rebase your development branch::
+
+    git checkout newfeature
+    git rebase master
+
+If required, squash some of your smaller commits down into a small number of larger more cohesive commits.
+
+After you have committed and pushed all your changes to GitHub, go to the page of your fork, select your development branch, and click on the pull request. Make sure to follow the pull request(PR) template.

docs/source/contribution/code_of_conduct.rst

@@ -0,0 +1,91 @@
+Code of conduct
+################
+
+.. contents:: Table of Contents:
+   :local:
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project
+and our community a harassment-free experience for everyone, regardless
+of age, body size, disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+-  Using welcoming and inclusive language
+-  Being respectful of differing viewpoints and experiences
+-  Gracefully accepting constructive criticism
+-  Focusing on what is best for the community
+-  Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+-  The use of sexualized language or imagery and unwelcome sexual
+   attention or advances
+-  Trolling, insulting/derogatory comments, and personal or political
+   attacks
+-  Public or private harassment
+-  Publishing others’ private information, such as a physical or
+   electronic address, without explicit permission
+-  Other conduct which could reasonably be considered inappropriate in a
+   professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of
+acceptable behavior and are expected to take appropriate and fair
+corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, or to ban
+temporarily or permanently any contributor for other behaviors that they
+deem inappropriate, threatening, offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies within all project spaces, and it also
+applies when an individual is representing the project or its community
+in public spaces. Examples of representing a project or community
+include using an official project e-mail address, posting via an
+official social media account, or acting as an appointed representative
+at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported by contacting the project team at [email protected].
+All complaints will be reviewed and investigated and will result in a
+response that is deemed necessary and appropriate to the circumstances.
+The project team is obligated to maintain confidentiality with regard to
+the reporter of an incident. Further details of specific enforcement
+policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in
+good faith may face temporary or permanent repercussions as determined
+by other members of the project’s leadership.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the `Contributor Covenant`_,
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+
+.. _Contributor Covenant: https://www.contributor-covenant.org

docs/source/contribution/docs_contribution.rst

@@ -0,0 +1,99 @@
+==================================
+Contributing to the documentation
+==================================
+
+PolyPhy  documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx.
+Since contributing to the documentation benefits everyone who uses PolyPhy, we strongly encourage you to help us improve the documentation.
+
+.. contents:: Table of Contents:
+   :local:
+
+
+Building the PolyPhy documentation
+-----------------------------------
+
+First, we recommend having an isolated virtual environment to avoid any problems with your installed Python packages
+(see see the docs on :ref:`creating a development environment <contributing_documentation>`).
+
+To install all the dependencies for the build, navigate to your local **docs/** directory in the console and run::
+
+    pip3 install -r requirements.txt
+
+After you have all the required dependencies installed, run::
+
+    make html
+
+Then you can find the HTML output in the folder **docs/build/html/**.
+
+You can now open output HTML in your browser by typing::
+
+    open build/html/index.html
+
+The first time you build the docs, it will take quite a while because it has to run all the code examples and build all the generated docstring pages. 
+In subsequent iterations, sphinx will try to only build the pages that have been modified.
+
+PolyPhy docstring guide
+-------------------------
+A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it 
+does without having to read the details of the implementation.
+
+**General rules:**
+
+Docstrings must be defined with three double-quotes. No blank lines should be left before or after the docstring.
+The text starts in the next line after the opening quotes. The closing quotes have their own line.
+
+    **Method**::
+
+        def foo(var1, var2, *args, only_seldom_used_keyword=0, **kwargs):
+            """
+            Summarize the function in one line.
+
+            Several sentences providing an extended description.
+
+            Parameters
+            ----------------------
+                var1 : array_like
+                    [description]
+                var2 : int
+                    [description]
+                *args : iterable
+                    [description].
+
+            Returns
+            -------
+            out : type
+                    [description]
+
+
+            See Also
+            -----------
+            [list]
+
+            References
+            ------------
+            [list]
+            """
+        pass
+
+
+    **Class**::
+
+        class foo(array):
+            """
+            Short/extended class description
+
+            Attributes
+            -----------
+            attributes_name : type
+                [attributes description]
+
+            Methods
+            ---------
+            method_name(method_parameters)
+                [method_description]
+            """
+
+
+
+
+

docs/source/contribution/index.rst

@@ -1,14 +1,18 @@
 ***************
-Contribution
+Development
 ***************
 
 
 .. toctree::
    :maxdepth: 2
 
-   pull_request
-   opening_issue
-   docstring_standard
+   code_contribution
+   docs_contribution
+   testing
+   troubleshooting
+   release_guide
+   code_of_conduct
+   licence