docs(tutorial): Add Codacy GitHub integration #22 (#145)

Codacy can assist new developers improve code quality. closes #22
imAsparky · Sep 28, 2021 · 1d86da3 · 1d86da3
1 parent fde72cf
commit 1d86da3
Show file tree

Hide file tree

Showing 15 changed files with 165 additions and 48 deletions.
diff --git a/docs/source/_static/imgs/tutorials/codacy-add-organisation.png b/docs/source/_static/imgs/tutorials/codacy-add-organisation.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-add-repo.png b/docs/source/_static/imgs/tutorials/codacy-add-repo.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-authorise-access.png b/docs/source/_static/imgs/tutorials/codacy-authorise-access.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-check-github-auth.png b/docs/source/_static/imgs/tutorials/codacy-check-github-auth.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-production-auth-page.png b/docs/source/_static/imgs/tutorials/codacy-production-auth-page.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-select-your-account.png b/docs/source/_static/imgs/tutorials/codacy-select-your-account.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-signup-page.png b/docs/source/_static/imgs/tutorials/codacy-signup-page.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-welcome-page.png b/docs/source/_static/imgs/tutorials/codacy-welcome-page.png
diff --git a/docs/source/_static/imgs/tutorials/codacy-where-to-install.png b/docs/source/_static/imgs/tutorials/codacy-where-to-install.png
diff --git a/docs/source/_static/imgs/tutorials/git-config-codacy.png b/docs/source/_static/imgs/tutorials/git-config-codacy.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -30,7 +30,6 @@ See a list of the Original and new In Progress Documents below.
 |
 .. toctree::
    :titlesonly:
-   :caption: In Progress Documentation:
 
    tutorials/index-tutorials
 

diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
@@ -99,7 +99,7 @@ Install cookiecutter:
 
 
 Step 3 : Generate Your Package
------------------------------
+------------------------------
 
 Now it's time to generate your Python package.
 
@@ -127,43 +127,6 @@ Install the new project's local development requirements:
 
     pip install -r requirements_dev.txt
 
-.. todo::
-    Add a how-to for Codacy integration to replace previous step 5 Travis setup.
-
-    See `Issue 22 <https://github.com/imAsparky/cookiecutter-py3-package/issues/22>`__.
-
-.. Step 5: Set Up Travis CI
-.. ------------------------
-
-.. `Travis CI com`_ is a continuous integration tool used to prevent
-.. integration problems. Every commit to the main branch will trigger automated
-.. builds of the application.
-
-.. Login using your Github credentials. It may take a few minutes for Travis CI
-.. to load up a list of all your GitHub repos. They will be listed with boxes to
-.. the left of the repo name, where the boxes have an ``X`` in them, meaning it is
-.. not connected to Travis CI.
-
-.. Add the public repo to your Travis CI account by clicking the ``X`` to switch
-.. it "on" in the box next to the ``mypackage`` repo. Do not try to follow the
-.. other instructions, that will be taken care of next.
-
-.. In your terminal, your virtualenv should still be activated. If it isn't,
-.. activate it now. Run the Travis CLI tool to do your Travis CI setup:
-
-.. .. code-block:: bash
-
-..     travis encrypt --add deploy.password
-
-.. This will:
-
-.. * Encrypt your PyPI password in your Travis config.
-.. * Activate automated deployment on PyPI when you push a new tag to main branch.
-
-.. See :ref:`travis-pypi-setup` for more information.
-
-.. .. _`Travis CI com`: https://travis-ci.com/
-
 
 Step 5: Set Up Read the Docs
 ----------------------------

diff --git a/docs/source/tutorials/index-tutorials.rst b/docs/source/tutorials/index-tutorials.rst
@@ -15,6 +15,7 @@ Tutorials
    tutorial-create-GH-repo
    tutorial-cookiecutter-create
    tutorial-git-first-push
+   tutorial-codacy-setup
 
 
 |
@@ -33,7 +34,6 @@ See a list of the Tutorials we have in progress below.
    tutorial-auto-changelog
    tutorial-pre-commit
    tutorial-console-script
-   tutorial-codacy-setup
    tutorial-PyPi
    tutorial-release-packagage
    tutorial-workflow
diff --git a/docs/source/tutorials/tutorial-GH-protected-branches.rst b/docs/source/tutorials/tutorial-GH-protected-branches.rst
@@ -3,7 +3,7 @@
 .. index:: GH-protected-branches ; Index
 
 
-.. _GH-protected-branches-index:
+.. _GH-protected-branches:
 
 =========================
 Github Protected Branches

diff --git a/docs/source/tutorials/tutorial-codacy-setup.rst b/docs/source/tutorials/tutorial-codacy-setup.rst
@@ -1,24 +1,179 @@
 .. include:: /extras.rst.txt
 .. highlight:: rst
-.. index:: Codacy-integration ; Index
+.. index:: codacy-integration ; Index
 
 
-.. _Codacy-integration-index:
-
+.. _codacy-integration:
 ==================
 Codacy Integration
 ==================
 
 
+Codacy [1]_ is an automated code review tool that monitors your technical debt,
+helps you improve your code quality, teaches best practices to developers,
+and helps you save time in code reviews.
+
+The GitHub integration incorporates Codacy into your existing Git workflows.
+
+If Codacy is not precisely what you are looking for, see Stackshare_ for some
+alternatives you may wish to explore.
+
+
+.. [1] `From the Codacy documentation <https://github.com/codacy/docs>`_
+
+.. _Stackshare: https://stackshare.io/codacy/alternatives
+
 |
 
-See a list of the steps below to get up get your Codacy integration up
+See a list of steps below to get your Codacy integration up
 and running fast.
 
 |
 
-.. todo::
+Pre-requisites
+==============
+
+A `GitHub <https://github.com/join>`_ account.
+
+:ref:`Create a GitHub repository.<create-GH-repo>`
+
+:ref:`Create a cookiecutter-py3-package.<cookie-create-pkg>`
+
+.. _codacy-integration-tutorial:
+Tutorial
+========
+
+.. important::
+
+  The user that enables the Codacy integration must have administrator access
+  to the repository. Codacy uses this GitHub user to suggest fixes on
+  pull requests.
+
+|
+
+Create a Codacy Account
+-----------------------
+
+|
+
+Visit `Codacy Sign Up Page <https://www.codacy.com/signup>`_ and click the
+`GitHub` option.
+
+.. image:: ../_static/imgs/tutorials/codacy-signup-page.png
+    :alt: Codacy Signup page
+
+
+Review the permissions you will provide Codacy Production to access you
+repository.
+
+If these meet your needs then click `Authorize Codacy Production`
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-production-auth-page.png
+    :alt: Codacy Production Auth page
+
+
+Fill in the Codacy Questions.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-welcome-page.png
+    :alt: Codacy Welcome page
+
+Adding a new organisation.  Click `Install and authorize Codacy`.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-add-organisation.png
+    :alt: Codacy add organisation page
+
+Select where you want to install and authorise Codacy.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-where-to-install.png
+    :alt: Codacy where to install page
+
+
+Select which of your repositories Codacy can access.
+
+`All repositories` allow Codacy to access all repositories without any further
+input from you.
+
+
+`Only select repositories` requires further input from you and provides more
+control over Codacy interaction with your GitHub repositories.
+
+After reviewing this page and making your choice, click `Install & Authorize`.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-authorise-access.png
+    :alt: Codacy authorise access page
+
+
+Open your GitHub Account and navigate to Settings->Applications and
+click `Configure`.
+
+Here, you can check that your selected Codacy options have been implemented
+correctly and make changes before final authorisation.
+
+Click `Save` to complete the Codacy authorisation.
+
+|
+
+.. image:: ../_static/imgs/tutorials/git-config-codacy.png
+    :alt: GitHub Codacy Configure page
+
+
+Sign back into Codacy and navigate to `Your Account` then `Access Management`.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-select-your-account.png
+    :alt: Codacy select your account
+
+
+Check GitHub has been succesfully authorised.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-check-github-auth.png
+    :alt: Codacy check GitHub authorised
+
+
+Go to `Choose an Organisation` and add your user.
+
+Codacy will present you with a list of authorised repositories.
+
+Click `Add` your new package.
+
+Your new package will now appear in the Repositories list.
+
+|
+
+.. image:: ../_static/imgs/tutorials/codacy-add-repo.png
+    :alt: Codacy select your repository
+
+
+.. tip::
+
+   After enabling this option, you can set Codacy as a required check before
+   merging your pull requests.
+
+   See :ref:`GitHub Protected Branches Tutorial<GH-protected-branches>`
+   for more information.
+
+
+.. admonition:: Need help with Codacy?
+
+    See `Codacy Community <https://community.codacy.com/>`_ if you have
+    questions or would like more information.
+
 
-    Write Codacy integration guide.
+Whats next?
+-----------
 
-    See `Issue-22 <https://github.com/imAsparky/cookiecutter-py3-package/issues/22>`_.
+Check out our other :ref:`Tutorials<tutorial-index>` for more information on
+how to get the most out of your cookiecutter package.