📚 docs(rst): Add contributing guidelines and roles section for rst do…

…cumentations

docs/contributing.rst

@@ -0,0 +1,174 @@
+Contributing
+============
+
+We’re excited that you’re interested in contributing to `dj-announcement-api`! Whether you’re fixing a bug, adding a feature, or improving the project, your help is appreciated.
+
+Overview
+--------
+
+- **Setting Up Your Environment**
+- **Testing Your Changes**
+- **Code Style Guidelines**
+- **Utilizing Pre-commit Hooks**
+- **Creating a Pull Request**
+- **Reporting Issues**
+- **Resources**
+
+Setting Up Your Environment
+---------------------------
+
+1. **Fork the Repository:**
+
+   Begin by forking the `dj-announcement-api` repository on GitHub. This creates your own copy where you can make changes.
+
+2. **Clone Your Fork:**
+
+   Use the following command to clone your fork locally:
+
+   .. code-block:: bash
+
+       git clone https://github.com/your-username/dj-announcement-api.git
+       cd dj-announcement-api
+
+3. **Install Dependencies:**
+
+   Install the necessary dependencies using ``Poetry``. If Poetry isn't installed on your machine, you can find installation instructions on the `Poetry website <https://python-poetry.org/docs/#installation>`_.
+
+   .. code-block:: bash
+
+       poetry install
+
+4. **Create a Feature Branch:**
+
+   It’s a good practice to create a new branch for your work:
+
+   .. code-block:: bash
+
+       git checkout -b feature/your-feature-name
+
+Testing Your Changes
+--------------------
+
+We use ``pytest`` for running tests. Before submitting your changes, ensure that all tests pass:
+
+.. code-block:: bash
+
+    poetry run pytest
+
+If you’re adding a new feature or fixing a bug, don’t forget to write tests to cover your changes.
+
+Code Style Guidelines
+----------------------
+
+Maintaining a consistent code style is crucial. We use ``black`` for code formatting and ``isort`` for import sorting. Make sure your code adheres to these styles:
+
+.. code-block:: bash
+
+    poetry run black .
+    poetry run isort .
+
+For linting, ``pylint`` is used to enforce style and catch potential errors:
+
+.. code-block:: bash
+
+    poetry run pylint django_announcement
+
+Utilizing Pre-commit Hooks
+--------------------------
+
+Pre-commit hooks are used to automatically check and format code before you make a commit. This ensures consistency and quality in the codebase.
+
+1. **Install Pre-commit:**
+
+   .. code-block:: bash
+
+       poetry add --group dev pre-commit
+
+2. **Set Up the Hooks:**
+
+   Install the pre-commit hooks by running:
+
+   .. code-block:: bash
+
+       poetry run pre-commit install
+
+3. **Set Up django_migration_linter:**
+
+    To ensure that ``django_migration_linter`` functions properly, add it to the INSTALLED_APPS section in your ``settings.py`` file:
+
+    .. code-block:: python
+
+        INSTALLED_APPS = [
+            # ...
+            "django_migration_linter"
+            # ...
+        ]
+
+This step integrates the migration linter into your Django project, allowing it to monitor migrations effectively.
+
+4. **Manual Hook Execution (Optional):**
+
+   To run all hooks manually on your codebase:
+
+   .. code-block:: bash
+
+       poetry run pre-commit run --all-files
+
+Creating a Pull Request
+-----------------------
+
+Once your changes are ready, follow these steps to submit them:
+
+1. **Commit Your Changes:**
+
+   Write clear and concise commit messages. Following the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_ format is recommended:
+
+   .. code-block:: bash
+
+       git commit -am 'refactor: update api announcement permission class'
+
+2. **Push Your Branch:**
+
+   Push your branch to your fork on GitHub:
+
+   .. code-block:: bash
+
+       git push origin feature/your-feature-name
+
+3. **Open a Pull Request:**
+
+   Go to the original `dj-announcement-api <https://github.com/Lazarus-org/dj-announcement-api>`_ repository and open a pull request. Include a detailed description of your changes and link any related issues.
+
+4. **Respond to Feedback:**
+
+   After submitting, a maintainer will review your pull request. Be prepared to make revisions based on their feedback.
+
+Reporting Issues
+----------------
+
+Found a bug or have a feature request? We’d love to hear from you!
+
+1. **Open an Issue:**
+
+   Head over to the `Issues` section of the `dj-announcement-api` repository and click "New Issue".
+
+2. **Describe the Problem:**
+
+   Fill out the issue template with as much detail as possible. This helps us understand and address the issue more effectively.
+
+Resources
+---------
+
+Here are some additional resources that might be helpful:
+
+- `Poetry Documentation <https://python-poetry.org/docs/>`_
+- `Black Documentation <https://black.readthedocs.io/en/stable/>`_
+- `isort Documentation <https://pycqa.github.io/isort/>`_
+- `pytest Documentation <https://docs.pytest.org/en/stable/>`_
+- `pylint Documentation <https://pylint.pycqa.org/en/latest/>`_
+- `django-migration-linter HomePage <https://github.com/3YOURMIND/django-migration-linter>`_
+- `Pre-commit Documentation <https://pre-commit.com/>`_
+
+----
+
+Thank you for your interest in contributing to `dj-announcement-api`! We look forward to your contributions.

docs/roles.rst

@@ -0,0 +1,187 @@
+Roles
+=====
+This section outlines the various roles within ``django-announcement-api``, detailing their permissions, actions, and throttling limits for both API and admin interactions. By defining role-based access control, the system ensures secure and efficient management of announcements, while providing flexibility for different user levels. Whether for anonymous users with no access, authenticated users interacting via the API, or administrators managing the announcement system, these roles offer a structured way to control who can create, retrieve, update, or delete announcements. This role-based framework helps maintain security, optimize performance, and support scalable system management.
+
+API Roles
+---------
+
+This section defines the user roles that interact with the `dj-announcement-api` and outlines their specific permissions, throttling limits, and actions available via the API. These roles allow for fine-grained control over who can retrieve, update, and delete announcements, and ensure that the system is scalable and secure for various levels of users.
+
+1. Anonymous Users
+~~~~~~~~~~~~~~~~~~
+Anonymous users are those who are not authenticated within the Django application. By default, anonymous users do not have access to most of the features in the announcement API.
+
+**Permissions**:
+  - **List Announcements**: ❌ (Disabled)
+  - **Retrieve Announcements**: ❌ (Disabled)
+
+**Throttling**:
+  - **Rate Limit**: N/A (No access)
+
+**Use Case**:
+  Anonymous users are generally restricted from interacting with the announcement system.
+
+2. Authenticated Users
+~~~~~~~~~~~~~~~~~~~~~~
+Authenticated users are regular users who have logged in to the Django application. They have basic permissions to view announcements.
+
+**Permissions**:
+  - **List announcements**: ✅ (If ``DJANGO_ANNOUNCEMENT_API_ALLOW_LIST`` is set to ``True``)
+  - **Retrieve announcements**: ✅ (If ``DJANGO_ANNOUNCEMENT_API_ALLOW_RETRIEVE`` is set to ``True``)
+
+**Throttling**:
+  - **Rate Limit**: ``30/minute`` (Configurable via ``DJANGO_ANNOUNCEMENT_AUTHENTICATED_USER_THROTTLE_RATE``)
+
+**Use Case**:
+  Authenticated users can view and retrieve their own announcements, but they cannot create or delete announcements.
+
+3. Staff Users (Admin)
+~~~~~~~~~~~~~~~~~~~~~~
+Staff users (admin or elevated users) have more privileges in terms of managing announcements, depending on the configuration of the settings.
+
+**Permissions**:
+  - **List announcements**: ✅ (If allowed by ``DJANGO_ANNOUNCEMENT_API_ALLOW_LIST``)
+  - **Retrieve announcements**: ✅ (If allowed by ``DJANGO_ANNOUNCEMENT_API_ALLOW_RETRIEVE``)
+
+**Throttling**:
+  - **Rate Limit**: ``100/minute`` (Configurable via ``DJANGO_ANNOUNCEMENT_STAFF_USER_THROTTLE_RATE``)
+
+**Use Case**:
+  Staff users are responsible for maintaining the announcement system. They view all announcements in the system.
+
+
+Customizing Roles with Extra Permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The system also allows for more fine-grained control through the ``DJANGO_ANNOUNCEMENT_API_EXTRA_PERMISSION_CLASS`` setting. You can define additional custom permission classes that extend the base permissions, adding conditions for API access. This is useful when specific user groups or roles require specialized access to certain announcement features.
+
+**Example**:
+You can create a custom permission class to restrict access to only users with a particular role or attribute:
+
+.. code-block:: python
+
+    DJANGO_ANNOUNCEMENT_API_EXTRA_PERMISSION_CLASS = (
+        "myapp.permissions.CustomPermissionClass"
+    )
+
+Role-Based Throttling
+~~~~~~~~~~~~~~~~~~~~~
+The package offers a **role-based throttling system**, allowing you to configure different API request rates for different user roles:
+
+  - **Authenticated Users**: Throttled at a rate of ``30 requests/minute`` by default.
+  - **Staff Users**: Throttled at a rate of ``100 requests/minute`` by default.
+  - **Superusers**: No throttling applied.
+
+This ensures that the API remains performant, and users with higher permissions are allowed to make more requests.
+
+**Example Throttle Configuration**:
+
+.. code-block:: python
+
+    DJANGO_ANNOUNCEMENT_AUTHENTICATED_USER_THROTTLE_RATE = "30/minute"
+    DJANGO_ANNOUNCEMENT_STAFF_USER_THROTTLE_RATE = "100/minute"
+    DJANGO_ANNOUNCEMENT_API_THROTTLE_CLASS = (
+        "django_announcement.api.throttlings.role_base_throttle.RoleBasedUserRateThrottle"
+    )
+
+Summary of Role Capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+
+   * - Role
+     - List announcements
+     - Retrieve announcements
+     - Throttle Rate
+   * - **Anonymous**
+     - ❌
+     - ❌
+     - N/A
+   * - **Authenticated**
+     - ✅
+     - ✅
+     - 30/minute
+   * - **Staff**
+     - ✅
+     - ✅
+     - 100/minute
+
+By configuring these roles, you ensure that each user type has access to the appropriate level of functionality within the announcement API, maintaining security and system stability.
+
+----
+
+Admin Role
+----------
+
+This section outlines the role of admins in interacting with the `dj-announcement-api` through the Django admin panel. Admin users have elevated privileges to manage announcements and their associated data.
+
+1. Admin Users
+~~~~~~~~~~~~~~
+Admin users have comprehensive permissions to manage announcements, including creating, updating, deleting, and viewing both active and expired announcements.
+
+**Permissions**:
+  - **Create announcements**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_ADD_PERMISSION`` is set to ``True``)
+  - **Modify announcements**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_CHANGE_PERMISSION`` is set to ``True``)
+  - **Delete announcements**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_DELETE_PERMISSION`` is set to ``True``)
+  - **Module permission**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_MODULE_PERMISSION`` is set to ``True``)
+
+
+**Use Case**:
+  Admin users are responsible for maintaining the announcement system, including managing audiences, categories, user announcement profiles and so on.
+
+
+Inline Admin Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+The admin panel includes two inline interfaces:
+- **AudienceInline**: Manage audiences associated with announcements directly.
+- **UserAudienceInline**: Manage audiences associated with user profiles directly.
+
+**Permissions**:
+  - **Create**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_INLINE_HAS_ADD_PERMISSION`` is set to ``True``)
+  - **Modify**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_INLINE_HAS_CHANGE_PERMISSION`` is set to ``True``)
+  - **Delete**: ✅ (If ``DJANGO_ANNOUNCEMENT_ADMIN_INLINE_HAS_DELETE_PERMISSION`` is set to ``True``)
+
+
+List Display
+~~~~~~~~~~~~
+The list view for announcements includes fields such as:
+- ``ID``: Unique identifier for each announcement.
+- ``Title``: Title of the announcement.
+- ``Category``: The category of the announcement.
+- ``Created at``: Creation time of the announcement.
+- ``Expires at``: Expiration time of the announcement.
+
+Filtering
+~~~~~~~~~
+Admins can filter announcements by:
+- ``created_at``
+- ``updated_at``
+- ``category``
+
+Search Functionality
+~~~~~~~~~~~~~~~~~~~~
+Search for announcements using:
+- ``ID``
+- ``Title``
+- ``Content``
+- ``audience name``
+
+Pagination
+~~~~~~~~~~
+The admin list view displays **10 announcements per page** by default for better management of large lists.
+
+Permissions Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Control admin permissions through settings:
+- ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_ADD_PERMISSION``: Controls "add" action.
+- ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_CHANGE_PERMISSION``: Controls "change" action.
+- ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_DELETE_PERMISSION``: Controls "delete" action.
+- ``DJANGO_ANNOUNCEMENT_ADMIN_HAS_MODULE_PERMISSION``: Controls "module" permission.
+
+Control inline admin permissions through settings:
+- ``DJANGO_ANNOUNCEMENT_ADMIN_INLINE_HAS_ADD_PERMISSION``: Controls "add" action.
+- ``DJANGO_ANNOUNCEMENT_ADMIN_INLINE_HAS_CHANGE_PERMISSION``: Controls "change" action.
+- ``DJANGO_ANNOUNCEMENT_ADMIN_INLINE_HAS_DELETE_PERMISSION``: Controls "delete" action.
+
+
+Most of the functionality within each admin interface adheres to these outlined guidelines, ensuring consistency and ease of management across all related models.