Rewrite main page of contibution guide

docs/source/contribute/documentation.rst

@@ -1,4 +1,4 @@
-.. _docs_guide:
+.. _contribute_docs:
 
 *******************
 Documentation guide
@@ -11,9 +11,9 @@ For the docstrings follow the |numpydoc|_ style guide.
 The complete documentation guide is not formed yet. But the following rules are already defined:
 
 * For the module guide each function and class has to have "Import" section.
-* Each class has to have "Creation" section. 
+* Each class has to have "Creation" section.
 * Each page of the module guide have to have the link to the corresponding page of the API.
 
 More rules will appear soon. The documentation guide will evolve until it will be complete.
-If you have any question about the writing of the documentation, please contact the 
+If you have any question about the writing of the documentation, please contact the
 |Author|_.

docs/source/contribute/index.rst

@@ -4,129 +4,109 @@
 Contributor`s guide
 *******************
 
-.. toctree::
-   :hidden:
-
-   features
-   bugs
-   documentation
-   contributors
 
 We welcome the contribution to the package!
 
 If you're interested in seeing who has already contributed to this project,
 please visit our :ref:`Contributors page <contribute_contributors>`.
-We appreciate all contributions, big or small, and we look forward to seeing your name on that list!
+We appreciate all contributions and look forward to see your name on that list!
 
 It is not necessary to be a programmer to contribute.
 You can help us with the documentation, :ref:`new features <contribute_feature>`
 and :ref:`finding bugs <contribute_bug>`.
 
 
 Contribution to the source code is summarized below.
+We assume that you have an account on `<https://github.com>`_
+and familiar with `Git <https://git-scm.com/>`_.
 
+Development workflow
+====================
 
+For the detailed explanation of the development workflow, please visit
+the corresponding links below.
 
-Fork
-====
-The first step is to fork the repository on GitHub.
-Go to |RAD-repo|_ and click on the "Fork" button.
-
-Clone
-=====
-Clone you forked repository to your local machine.
+1. Fork and clone.
 
-If you are using ssh-key:
+   * Go to the |RAD-repo|_ and click on the "Fork" button.
+     Now you have your own copy of the RAD-tools repository in your GitHub account.
+   * Clone you copy of the repository to your local machine:
 
-.. code-block:: bash
+     - If you are using ssh-key::
 
-   git clone https://github.com/your-username/rad-tools.git
+         git clone https://github.com/your-username/rad-tools.git
 
-If you are not using ssh-key:
+     - If you are not using ssh-key::
 
-.. code-block:: bash
+         git clone [email protected]:your-username/rad-tools.git
 
-   git clone [email protected]:your-username/rad-tools.git
+   * Change the directory::
 
-Change the directory:
+      cd rad-tools
+   * Add the upstream repository::
 
-.. code-block:: bash
+      git remote add upstream https://github.com/adrybakov/rad-tools.git
 
-   cd rad-tools
+2. Set up the environment.
 
-Environment
-===========
+   We recommend to use virtual environment. Once the virtual environment is created,
+   you can install requirements:
 
-Set up the necessary environment. We recommend to use virtual environment.
-Once the virtual environment is created, you can install requirements:
+   * For the package development::
 
-* For the package development:
+      pip install -r requirements.txt
+   * For the docs::
 
-.. code-block:: bash
+      pip install -r docs/requirements.txt
+   * For the tests::
 
-   pip install -r requirements.txt
+      pip install -r utest/requirements.txt
 
-* For the docs:
+3. Develop the contribution.
 
-.. code-block:: bash
+   * Create a dedicated branch for your feature, that you are going to develop::
 
-   pip install -r docs/requirements.txt
+      git checkout -b feature-name
 
-* For the tests:
+   * Develop your contribution. Commit your progress locally
+     (`git-add <https://git-scm.com/docs/git-add>`_
+     and `git-commit <https://git-scm.com/docs/git-commit>`_).
+     Use meaningful commit messages. Write `tests <contribute_tests>`.
+     Write `documentation <contribute_docs>`.
 
-.. code-block:: bash
+4. Submit your contribution.
 
-   pip install -r utest/requirements.txt
-
-Develop
-=======
-
-Develop your contribution. Commit your progress locally. Use meaningful commit messages.
-If you want to create new script for command line interface, then check out :ref:`contribute_script` guide.
-
-.. toctree::
-   :hidden:
-
-   script
+   * Push the changes to your forked repository::
 
-Test
-====
+      git push origin feature-name
 
-Write unit tests for the developed code. We recommend to write tests before the code.
-Test files are located in the "utest" directory. the structure of the source code directory
-("radtools") and the test directory ("utest") is loosely the same.
+   * Go to your forked repository on GitHub and click on the
+     green "Compare & pull request" button.
+     Describe your contribution and submit the pull request.
+     Please mention the issue number if it is related to any.
 
-Run the tests locally:
+5. Review and merge.
 
-.. code-block:: bash
+   * Once the pull request is submitted, the code will be reviewed.
+     If there are any comments, please fix them.
+   * Once the pull request is approved, it will be merged to the
+     `stable <https://github.com/adrybakov/rad-tools>`_ or
+     `dev <https://github.com/adrybakov/rad-tools/tree/dev>`_ branch.
 
-   make test
 
-Docs
-====
+Development process in details
+==============================
 
-If you have developed a new feature, please add the description to the docs.
-Make sure to follow :ref:`docs_guide`.
-
-Build the docs locally:
-
-.. code-block:: bash
-
-   make html
-
-Doctest
-=======
-
-Run doctest locally:
-
-.. code-block:: bash
+.. toctree::
+   :hidden:
 
-   make doctest
+   contributors
 
-Pull request
-============
+.. toctree::
+   :maxdepth: 2
 
-Once you are ready with your contribution,
-push your changes to your forked repository and create a pull request.
-Please add the description to the pull request.
-Mention the issue number if it is related to any.
+   features
+   bugs
+   documentation
+   tests
+   script

docs/source/contribute/tests.rst

@@ -0,0 +1,7 @@
+.. _contribute_tests:
+
+**********
+Test guide
+**********
+
+Work in progress.