Merge pull request #37 from ARYAN-NIKNEZHAD/doc/package-documentation

📚 Add package documentation

README.md

@@ -15,80 +15,96 @@ The [django-iranian-cities](https://github.com/sageteam-org/django-iranian-citie
 - [Project Detail](#project-detail)
 - [Get Started](#getting-started)
 - [Usage](#usage)
-- [Admin](#admin)
+- [Settings](#settings)
 - [Git Rules](#git-rules)
 
 ## Project Detail
 
-- Language: Python > 3.6
-- Framework: Django > 3.2
+- Language: Python > 3.8
+- Framework: Django > 4.2
 
 ## Getting Started
 
-First you have to install package using pip:
+1. **Install the package**:
 
-```shell
-$ pip install django-iranian-cities
-```
+    ```shell
+    $ pip install django-iranian-cities
+    ```
 
-Then you should add `iranian_cities` to INSTALLED_APPS:
+2. **Add `iranian_cities` to INSTALLED_APPS in your Django settings**:
 
-```python
-INSTALLED_APPS = [
-    ...
-    'iranian_cities',
-    ...
-]
-```
+    ```python
+    INSTALLED_APPS = [
+        ...
+        'iranian_cities',
+        ...
+    ]
+    ```
 
-Now you can migrate to apply model changes:
+3. **Run migrations to apply model changes**:
 
-```shell
-$ python manage.py migrate
-```
+    ```shell
+    $ python manage.py migrate
+    ```
 
-For generating all data you can run this command:
+4. **Generate Data**:
+To populate the database with Iranian cities data, use the provided management command. This command will:
 
-```shell
-$ python manage.py generate_city
-```
+   - Check if there is existing data in the tables.
+   - Prompt you to confirm if you want to **flush** the tables if they already contain data.
+   - Read **CSV** files and populate the `Province`, `County`, `District`, `City`, `RuralDistrict`, and `Village` tables with data.
 
-NOTE: you should run this command once (if you want to run again flush db or delete all objects in iranian_cities app)
+    ```shell
+    $ python manage.py generate_city
+    ```
+    If **tables** contain data, you will be prompted to either **flush** them or **cancel** the operation.
 
 ## Usage
 
-You can use field like this:
-
-```python
-from django.db import models
-from iranian_cities.fields import ProvinceField
-
-class TestModel(models.Model):
-    province = ProvinceField()
-
-list of fields:
-
-- ProvinceField
-- CountyField
-- DistrictField
-- CityField
-- RuralDistrictField
-- VillageField
-
-
-## Admin
-
-You can also use admin mixin class:
-
+You can use the provided fields and admin mixin in your Django models:
+
+- **Fields**:
+    ```python
+    from django.db import models
+    from iranian_cities.fields import ProvinceField
+
+    class TestModel(models.Model):
+        province = ProvinceField()
+
+    ```
+    **list of fields**:
+    - ProvinceField
+    - CountyField
+    - DistrictField
+    - CityField
+    - RuralDistrictField
+    - VillageField
+
+- **Admin**:
+    ```python
+    from django.contrib import admin
+    from iranian_cities.admin import IranianCitiesAdmin
+    from test_app.models import TestModel
+
+    @admin.register(TestModel)
+    class TestModelAdmin(IranianCitiesAdmin):
+        pass
+    ```
+
+## Settings
+The package uses several settings for configuration. Make sure the following settings are defined in your `settings.py` file:
 ```python
-from django.contrib import admin
-from iranian_cities.admin import IranianCitiesAdmin
-from test_app.models import TestModel
-
-@admin.register(TestModel)
-class TestModelAdmin(IranianCitiesAdmin):
-    pass
+IRANIAN_CITIES_ADMIN_ADD_READONLY_ENABLED = True
+IRANIAN_CITIES_ADMIN_DELETE_READONLY_ENABLED = True
+IRANIAN_CITIES_ADMIN_CHANGE_READONLY_ENABLED = True
+IRANIAN_CITIES_ADMIN_INLINE_ENABLED = False
 ```
+Explanation of **settings**:
+
+- `IRANIAN_CITIES_ADMIN_ADD_READONLY_ENABLED`: When set to `True`, users can add new entries to the admin interface. Set to `False` to disable adding entries.
+- `IRANIAN_CITIES_ADMIN_DELETE_READONLY_ENABLED`: When set to `True`, users can delete existing entries in the admin interface. Set to `False` to disable deleting entries.
+- `IRANIAN_CITIES_ADMIN_CHANGE_READONLY_ENABLED`: When set to `True`, users can change existing entries in the admin interface. Set to `False` to disable changes.
+- `IRANIAN_CITIES_ADMIN_INLINE_ENABLED`: When set to `True`, inline admin forms are enabled based on the model type. Set to `False` to disable inline forms.
 
 ![Admin](https://github.com/sageteam-org/django-iranian-cities/blob/master/docs/images/admin.jpg?raw=true)
 

docs/contributing.rst

@@ -0,0 +1,149 @@
+Contributing
+=====================================
+
+Thank you for considering contributing to `django-iranian-cities`! We welcome contributions from the community to help make this project better.
+
+Table of Contents
+-----------------
+
+- `Getting Started`
+- `Running Tests`
+- `Code Style`
+- `Pre-commit Hooks`
+  - `Setting Up Pre-commit Hooks`
+- `Submitting a Pull Request`
+- `Reporting Issues`
+- `Additional Resources`
+
+Getting Started
+---------------
+
+1. **Fork the repository on GitHub**:
+
+   Go to the `django-iranian-cities` repository and click on the "Fork" button in the top-right corner.
+
+2. **Clone your fork locally**:
+
+   .. code-block:: bash
+
+       git clone https://github.com/your-username/django-iranian-cities.git
+       cd django-iranian-cities
+
+3. **Install dependencies using Poetry**:
+
+   If you don't have Poetry installed, you can install it by following the instructions on the `Poetry website <https://python-poetry.org/docs/#installation>`_.
+
+   .. code-block:: bash
+
+       poetry install
+
+4. **Create a new branch for your feature or bugfix**:
+
+   .. code-block:: bash
+
+       git checkout -b feature/your-feature
+
+Running Tests
+-------------
+
+First check out `Django Iranian Cities Pytest Guide <Django_Iranian_Cities_Pytest_Guide.md>` for writing tests.
+
+We use `pytest` for testing. To run the tests, execute:
+
+.. code-block:: bash
+
+    poetry run pytest
+
+Ensure that all tests pass before submitting a pull request.
+
+Code Style
+----------
+
+We use `black` and `isort` to format our code. Please ensure your code is formatted correctly before submitting a pull request:
+
+.. code-block:: bash
+
+    poetry run black .
+    poetry run isort .
+
+Additionally, we use `flake8` and `pylint` for linting. You can run these tools to check for code style issues:
+
+.. code-block:: bash
+
+    poetry run flake8
+    poetry run pylint django_iranian_cities
+
+Pre-commit Hooks
+----------------
+
+We use `pre-commit` to ensure code quality and consistency. Pre-commit hooks will run automatically before each commit to check and format the code.
+
+Setting Up Pre-commit Hooks
+
+1. **Install pre-commit**:
+
+   .. code-block:: bash
+
+       poetry add --dev pre-commit
+
+2. **Install the pre-commit hooks**:
+
+   .. code-block:: bash
+
+       poetry run pre-commit install
+
+3. **Run pre-commit hooks manually (optional but recommended before committing)**:
+
+   .. code-block:: bash
+
+       poetry run pre-commit run --all-files
+
+The pre-commit configuration is defined in the `.pre-commit-config.yaml` file. Make sure to review and understand the hooks configured.
+
+Submitting a Pull Request
+-------------------------
+
+1. **Commit your changes**:
+
+   Write clear and descriptive commit messages. Follow the guidelines in the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_ specification if possible.
+
+   .. code-block:: bash
+
+       git commit -am 'feat: add new email feature'
+
+2. **Push to the branch**:
+
+   .. code-block:: bash
+
+       git push origin feature/your-feature
+
+3. **Open a pull request on GitHub**:
+
+   Go to the original repository on GitHub and open a pull request. Provide a clear and descriptive title and description for your pull request. Link to any relevant issues or discussions.
+
+4. **Wait for review**:
+
+   One of the project maintainers will review your pull request. Be responsive to feedback and be prepared to make changes if necessary.
+
+Reporting Issues
+----------------
+
+If you find a bug or have a feature request, please open an issue on GitHub. Provide as much detail as possible to help us understand and address the issue:
+
+1. **Go to this link below**:
+    - `Issue Link <https://github.com/sageteamorg/django-iranian-cities/issues>`_
+2. **Click on "New issue".**
+3. **Fill out the issue template with relevant details.**
+
+Additional Resources
+---------------------
+
+- `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/>`_
+- `flake8 Documentation <https://flake8.pycqa.org/en/latest/>`_
+- `pylint Documentation <https://pylint.pycqa.org/en/latest/>`_
+- `Pre-commit Documentation <https://pre-commit.com/>`_
+
+Thank you for contributing!

docs/index.rst

@@ -39,8 +39,8 @@ This app supports the following combinations of Django and Python:
 ==========  =======================
   Django      Python
 ==========  =======================
-3.2         3.6, 3.7, 3.8, 3.9, 3.10
-4.1         3.8, 3.9, 3.10
+4.2         3.8, 3.9, 3.10, 3.11, 3.12
+5.0         3.10, 3.11, 3.12
 ==========  =======================
 
 Documentation
@@ -51,8 +51,10 @@ Documentation
 
    quick_start
    usage
+   settings
+   pytest_guide
+   contributing
    rules
-   team
 
 Issues
 ------