docs: general formatting, fix links, cleanups, rewrites

CONTRIBUTING.rst

@@ -57,7 +57,7 @@ Before You Open a Pull Request
 -  Your code is presentable and you have **not** committed extra files
    (think your credentials, IDE config files, cached directories, build
    directories, etc.)
--  You’ve written unit tests for the changes you’ve made, and that they
+-  You've written unit tests for the changes you've made, and that they
    cover all the code you wrote (or effectively all, given the
    circumstances)
 
@@ -123,7 +123,7 @@ Assuming you are on your working branch:
    git rebase master
 
 If you have changed files that were also changed in the intervening
-merge, ``git rebase`` may report merge conflicts. If this happens, don’t
+merge, ``git rebase`` may report merge conflicts. If this happens, don't
 panic! Use ``git status`` and ``git diff`` to determine which files
 conflict and where, use an editor to fix the conflicts, then stage the
 formerly-conflicting files with ``git add FILE``. Finally, use

README.rst

@@ -1,45 +1,48 @@
 .. raw:: html
 
-   <p align="center">
-      <img width="25%" src="https://github.com/ubclaunchpad/rocket2/blob/master/docs/rocket-logo.png?raw=true" />
-   </p>
-
-   <h1 align="center">Rocket 2</h1>
-
-   <p align="center">
-      Rocket 2 is the official <a href="https://ubclaunchpad.com">UBC Launch Pad</a>
-      Slack bot and team management platform.
-   </p>
-
-   <p align="center">
-      <a href="https://github.com/ubclaunchpad/rocket2/actions?query=workflow%3APipeline">
-         <img src="https://github.com/ubclaunchpad/rocket2/workflows/Pipeline/badge.svg">
-      </a>
-      <a href="https://codecov.io/gh/ubclaunchpad/rocket2">
-         <img src="https://codecov.io/gh/ubclaunchpad/rocket2/branch/master/graph/badge.svg">
-      </a>
-      <a href="https://github.com/ubclaunchpad/inertia">
-         <img src="https://img.shields.io/badge/deploying%20with-inertia-blue.svg">
-      </a>
-      <a href="https://rocket2.readthedocs.io">
-         <img src="https://readthedocs.org/projects/rocket2/badge/?version=latest">
-      </a>
-   </p>
+    <p align="center">
+        <img width="25%" src="https://github.com/ubclaunchpad/rocket2/blob/master/docs/rocket-logo.png?raw=true" />
+    </p>
+
+    <h1 align="center">Rocket 2</h1>
+
+    <p align="center">
+        Rocket 2 is the official <a href="https://ubclaunchpad.com">UBC Launch Pad</a>
+        Slack bot and team management platform.
+    </p>
+
+    <p align="center">
+        <a href="https://github.com/ubclaunchpad/rocket2/actions?query=workflow%3APipeline">
+           <img src="https://github.com/ubclaunchpad/rocket2/workflows/Pipeline/badge.svg">
+        </a>
+        <a href="https://codecov.io/gh/ubclaunchpad/rocket2">
+           <img src="https://codecov.io/gh/ubclaunchpad/rocket2/branch/master/graph/badge.svg">
+        </a>
+        <a href="https://github.com/ubclaunchpad/inertia">
+           <img src="https://img.shields.io/badge/deploying%20with-inertia-blue.svg">
+        </a>
+        <a href="https://rocket2.readthedocs.io">
+           <img src="https://readthedocs.org/projects/rocket2/badge/?version=latest">
+        </a>
+    </p>
 
 |
 
-Rocket 2 is a from-the-ground-up rewrite of the `original Rocket <https://github.com/ubclaunchpad/rocket>`_,
+Rocket 2 is a from-the-ground-up rewrite of the `original Rocket`_,
 and it is a Slack bot that aims to be a ChatOps-style tool for team management
 across platforms like GitHub and Google Drive, with extensive configuration
 options so that it can be used by other organizations as well. Rocket 2 is used,
-built, and maintained with ❤️ by `UBC Launch Pad <https://ubclaunchpad.com>`_,
-UBC's student-run software engineering club.
+built, and maintained with ❤️ by `UBC Launch Pad`_, UBC's student-run software
+engineering club.
+
+.. _UBC Launch Pad: https://ubclaunchpad.com
+.. _original Rocket: https://github.com/ubclaunchpad/rocket
 
 .. list-table::
    :widths: 3 50
    :header-rows: 1
 
-   * - 
+   * -
      - Main features
    * - 💬
      - **Unix-style command system in Slack** - invoke commands with a simple ``/rocket`` in Slack
@@ -57,14 +60,17 @@ UBC's student-run software engineering club.
 📦 Usage
 --------
 
-Check out our `command reference pages <https://rocket2.readthedocs.io/en/latest/docs/UserCommands.html>`_
-to get started interacting with Rocket, or take a look at how Rocket is used at UBC Launch Pad
-in the `Launch Pad handbook <https://docs.ubclaunchpad.com/handbook/tools/slack#rocket>`_.
+Check out our `command reference pages`_ to get started interacting with
+Rocket, or take a look at how Rocket is used at UBC Launch Pad in
+the `Launch Pad handbook`_.
+
+To set up a Rocket instance for your organization, refer to the `deployment`_
+and `configuration`_ documentation.
 
-To set up a Rocket instance for your organization, refer to the
-`deployment <https://rocket2.readthedocs.io/en/latest/docs/Deployment.html>`_
-and `configuration <https://rocket2.readthedocs.io/en/latest/docs/Config.html>`_
-documentation.
+.. _deployment: docs/Deployment.html
+.. _configuration: docs/Config.html
+.. _command reference pages: docs/UserCommands.html
+.. _Launch Pad handbook: https://docs.ubclaunchpad.com/handbook/tools/slack#rocket
 
 |
 
@@ -73,8 +79,9 @@ documentation.
 
 Any contribution (pull requests, feedback, bug reports, ideas, etc.) is welcome!
 
-Please refer to our `contribution guide <https://rocket2.readthedocs.io/en/latest/CONTRIBUTING.html>`__
-for contribution guidelines as well as detailed guides to help you get started
-with Rocket 2's codebase.
+Please refer to our `contribution guide`_ for contribution guidelines as well as
+detailed guides to help you get started with Rocket 2's codebase.
+
+.. _contribution guide: CONTRIBUTING.html
 
 |

app/controller/command/commands/karma.py

@@ -30,7 +30,11 @@ def __init__(self, db_facade):
         self.help = self.get_help()
 
     def init_subparsers(self) -> _SubParsersAction:
-        """Initialize subparsers for karma command."""
+        """
+        Initialize subparsers for karma command.
+
+        :meta private:
+        """
         subparsers: _SubParsersAction = \
             self.parser.add_subparsers(dest="which")
 

app/controller/command/commands/project.py

@@ -289,7 +289,7 @@ def unassign_helper(self,
 
         :param project_id: project ID of project to unassign team from
         :param user_id: user ID of the calling user
-        :return: returns lookup error if the project, assigned team or calling
+        :return: error string if the project, assigned team or calling
                  user could not be found, else permission error if calling
                  user is not a team lead of the team to unassign,
                  otherwise success message
@@ -321,7 +321,7 @@ def edit_helper(self,
 
         :param project_id: project ID of the project in the database to edit
         :param param_list: Dict of project parameters that are to be edited
-        :return: returns edit message if project is successfully edited, or an
+        :return: edit message if project is successfully edited, or an
                  error message if the project was not found in the database
         """
         logging.debug("Handling project edit subcommand")
@@ -354,7 +354,7 @@ def assign_helper(self,
         :param user_id: user ID of the calling user
         :param force: specify if an error should be raised if the project
                       is assigned to another team
-        :return: returns lookup error if the project could not be found or no
+        :return: error string if the project could not be found or no
                  team has the specified GitHub team name or if the calling
                  user is not in the database, else permission error if calling
                  user is not a team lead, else an assignment error if the
@@ -404,7 +404,7 @@ def delete_helper(self,
         :param user_id: user ID of the calling user
         :param force: specify if an error should be raised if the project
                       is assigned to a team
-        :return: returns lookup error if the project, assigned team, or user
+        :return: error string if the project, assigned team, or user
                  could not be found, else an assignment error if the project
                  is assigned to a team, otherwise success message
         """

app/controller/command/commands/team.py

@@ -40,7 +40,7 @@ def __init__(self,
         :param db_facade: Given Dynamo_DB Facade
         :param gh: Given Github Interface
         :param sc: Given Slack Client Interface
-        "param gcp: Given GCP client
+        :param gcp: Given GCP client
         """
         logging.info("Initializing TeamCommand instance")
         self.facade = db_facade
@@ -55,7 +55,11 @@ def __init__(self,
         self.help = self.get_help()
 
     def init_subparsers(self) -> _SubParsersAction:
-        """Initialize subparsers for team command."""
+        """
+        Initialize subparsers for team command.
+
+        :meta private:
+        """
         subparsers = self.parser.add_subparsers(dest="which")
 
         """Parser for list command."""
@@ -635,7 +639,8 @@ def refresh_helper(self, user_id) -> ResponseTuple:
         Ensure that the local team database is the same as GitHub's.
 
         In the event that our local team database is outdated compared to
-        the teams on GitHub, this command can be called to fix things.
+        the teams on GitHub, this command can be called to fix these
+        inconsistencies.
 
         :return: error message if user has insufficient permission level
                  otherwise returns success messages with # of teams changed

app/controller/command/commands/user.py

@@ -41,7 +41,11 @@ def __init__(self,
         self.gcp = gcp
 
     def init_subparsers(self) -> _SubParsersAction:
-        """Initialize subparsers for user command."""
+        """
+        Initialize subparsers for user command.
+
+        :meta private:
+        """
         subparsers = self.parser.add_subparsers(dest="which")
 
         # Parser for view command
@@ -223,8 +227,8 @@ def edit_helper(self,
 
         :param user_id: Slack ID of user who is calling the command
         :param param_list: List of user parameters that are to be edited
-        :return: returns error message if not admin and command
-                   edits another user, returns edit message if user is edited
+        :return: error message if not admin and command edits another user,
+            or the edit message if user is edited
         """
         is_admin = False
         edited_user = None

app/controller/webhook/github/core.py

@@ -54,7 +54,7 @@ def verify_hash(self, request_body: bytes, xhub_signature: str):
 
         :param request_body: Byte string of the request body
         :param xhub_signature: Hashed signature to validate
-        :return: Return True if the signature is valid, False otherwise
+        :return: True if the signature is valid, False otherwise
         """
         h = hmac.new(bytes(self.__secret, encoding='utf8'),
                      request_body, hashlib.sha1)

app/model/base.py

@@ -33,7 +33,7 @@ def from_dict(cls: Type[T], d: Dict[str, Any]) -> T:
         Convert dict response object to data model object.
 
         :param d: the dictionary representing a data model
-        :return: returns converted data model object.
+        :return: the converted data model object.
         """
         pass
 
@@ -44,6 +44,6 @@ def is_valid(cls: Type[T], model: T) -> bool:
         Return true if this data model has no missing required fields.
 
         :param model: data model object to check
-        :return: return true if this data model has no missing required fields
+        :return: true if this data model has no missing required fields
         """
         pass

app/model/team.py

@@ -62,7 +62,7 @@ def from_dict(cls: Type[T], d: Dict[str, Any]) -> T:
         Convert dict response object to team model.
 
         :param d: the dictionary representing a team
-        :return: returns converted team model.
+        :return: the converted team model.
         """
         team = cls(d['github_team_id'],
                    d['github_team_name'],
@@ -113,7 +113,7 @@ def is_valid(cls: Type[T], team: T) -> bool:
             - ``github_team_id``
 
         :param team: team to check
-        :return: returns true if this team has no missing required fields
+        :return: true if this team has no missing required fields
         """
         return len(team.github_team_name) > 0 and\
             len(team.github_team_id) > 0

app/model/user.py

@@ -84,7 +84,7 @@ def from_dict(cls: Type[T], d: Dict[str, Any]) -> T:
         Convert dict response object to user model.
 
         :param d: the dictionary representing a user
-        :return: returns converted user model.
+        :return: the converted user model.
         """
         user = cls(d['slack_id'])
         user.email = d.get('email', '')
@@ -110,7 +110,7 @@ def is_valid(cls: Type[T], user: T) -> bool:
             - ``permissions_level``
 
         :param user: user to check
-        :return: return true if this user has no missing required fields
+        :return: true if this user has no missing required fields
         """
         return len(user.slack_id) > 0
 

conf.py

@@ -23,9 +23,9 @@
 author = 'UBC Launch Pad'
 
 # The short X.Y version
-version = '1.0'
+version = '2.0'
 # The full version, including alpha/beta/rc tags
-release = '1.0.0'
+release = '2.0.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -42,6 +42,10 @@
     'sphinx_autodoc_typehints',
 ]
 
+# Config options for the extensions
+typehints_fully_qualified = True
+always_document_param_types = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['docs/_templates']
 

config/__init__.py

@@ -118,7 +118,7 @@ def __init__(self, missing_config_fields):
         """
         Initialize a new MissingConfigError.
 
-        :param: missing_config_fields List of missing config variables
+        :param missing_config_fields: the missing config variables
         """
         self.error = 'Please set the following env variables:\n' + \
             '\n'.join(missing_config_fields)