Merge pull request #52 from MEHRSHAD-MIRSHEKARY/docs/rst

📚 Docs/rst

django_announcement/admin/audience.py

@@ -9,7 +9,6 @@
 class AudienceAdmin(BaseModelAdmin):
     list_display = BaseModelAdmin.list_display + ["name", "created_at", "updated_at"]
     list_display_links = ["name"]
-    list_filter = BaseModelAdmin.list_filter + ["updated_at"]
     search_fields = BaseModelAdmin.search_fields + ["name", "description"]
     fieldsets = [
         (

docs/api_guide.rst

@@ -0,0 +1,169 @@
+API Guide
+=========
+
+This section provides a detailed overview of the Django Announcement API, allowing users to manage announcements efficiently. The API exposes two main endpoints:
+
+
+Announcements API
+-----------------
+
+The ``announcement/announcements/`` endpoint provides the following features:
+
+- **List active announcements**:
+
+  Fetches all active announcements for the authenticated user (all announcements for admin users). Controlled by the ``DJANGO_ANNOUNCEMENT_API_ALLOW_LIST`` setting.
+
+- **Retrieve an announcement**:
+
+  Retrieves a specific active announcement by its ID. Controlled by the ``DJANGO_ANNOUNCEMENT_API_ALLOW_RETRIEVE`` setting.
+
+
+Example Responses
+-----------------
+
+Here are some examples of responses for each action:
+
+
+**List announcements with full details**:
+
+.. code-block:: text
+
+   GET /announcement/announcements/
+
+   Response:
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   "results": [
+        {
+            "id": 1,
+            "title": "test announcement",
+            "content": "some content",
+            "category": {
+                "id": 1,
+                "name": "test category",
+                "description": "something!"
+            },
+            "audience": [
+                {
+                    "id": 1,
+                    "name": "new audience",
+                    "description": null
+                },
+                {
+                    "id": 2,
+                    "name": "another audience",
+                    "description": null
+                },
+            ],
+            "published_at": "2024-10-18T08:49:52Z",
+            "expires_at": null,
+            "attachment": null,
+            "created_at": "2024-10-18T08:49:09Z",
+            "updated_at": "2024-10-18T09:10:41.743564Z"
+        }
+   ]
+
+If the ``DJANGO_ANNOUNCEMENT_SERIALIZER_INCLUDE_FULL_DETAILS`` setting is ``True``, this detailed response will be returned for all users.
+
+**List announcements with simplified data**:
+
+.. code-block:: text
+
+   GET /announcement/announcements/
+
+   Response:
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   "results": [
+        {
+            "id": 1,
+            "title": "first announcement",
+            "content": "some content",
+            "category": {
+                "id": 1,
+                "name": "test category",
+                "description": "something!"
+            },
+            "published_at": "2024-10-18T08:49:52Z",
+            "expires_at": null,
+            "attachment": null,
+            "created_at": "2024-10-18T08:49:09Z",
+            "updated_at": "2024-10-18T09:10:41.743564Z"
+        },
+
+      ...
+   ]
+
+This response is returned when ``DJANGO_ANNOUNCEMENT_SERIALIZER_INCLUDE_FULL_DETAILS`` is set to ``False``. Admins always see full details.
+
+
+.. note::
+
+ you can exclude Any fields with a ``null`` value in the response output by adding this config in your ``settings.py``:
+.. code-block:: python
+
+   DJANGO_ANNOUNCEMENT_SERIALIZER_EXCLUDE_NULL_FIELDS = True
+
+Throttling
+----------
+
+The API includes a built-in throttling mechanism that limits the number of requests a user can make based on their role. You can customize these throttle limits in the settings file.
+
+To specify the throttle rates for authenticated users and staff members, add the following in your settings:
+
+.. code-block:: ini
+
+   DJANGO_ANNOUNCEMENT_AUTHENTICATED_USER_THROTTLE_RATE = "100/day"
+   DJANGO_ANNOUNCEMENT_STAFF_USER_THROTTLE_RATE = "60/minute"
+
+These settings limit the number of requests users can make within a given timeframe.
+
+**Note:** You can define custom throttle classes and reference them in your settings.
+
+
+Filtering, Ordering, and Search
+-------------------------------
+
+The API supports filtering, ordering, and searching of announcements. Filter Class can be applied optionally, allowing users to narrow down results.
+
+Options include:
+
+- **Filtering**: By default filtering feature is not included, If you want to use this, you need to add ``django_filters`` to your `INSTALLED_APPS` and provide the path to the ``AnnouncementFilter`` class (``"django_announcement.api.filters.announcement_filter.AnnouncementFilter"``). Alternatively, you can use a custom filter class if needed.
+
+  - **Note**: for more clarification, refer to the `DJANGO_ANNOUNCEMENT_API_FILTERSET_CLASS` in :doc:`Settings <settings>` section.
+
+- **Ordering**: Results can be ordered by fields such as ``id``, ``timestamp``, or ``public``.
+
+- **Search**: You can search fields like ``verb`` and ``description``.
+
+These fields can be customized by adjusting the related configurations in your Django settings.
+
+
+Pagination
+----------
+
+The API supports limit-offset pagination, with configurable minimum, maximum, and default page size limits. This controls the number of results returned per page.
+
+Permissions
+-----------
+
+The base permission for all endpoints is ``IsAuthenticated``, meaning users must be logged in to access the API. You can extend this by creating custom permission classes to implement more specific access control.
+
+For instance, you can allow only specific user roles to perform certain actions.
+
+Parser Classes
+--------------
+
+The API supports multiple parser classes that control how data is processed. The default parsers include:
+
+- ``JSONParser``
+- ``MultiPartParser``
+- ``FormParser``
+
+You can modify parser classes by updating the API settings to include additional parsers or customize the existing ones to suit your project.
+
+----
+
+Each feature can be configured through the Django settings file. For further details, refer to the :doc:`Settings <settings>` section.

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.