docs: Rehaul for easy-to-follow approach

CHANGELOG.rst

@@ -2,7 +2,7 @@ Release Notes
 -------------
 
 [3.0.1]
-^^^^^
+^^^^^^^
 
 Added
 """""
@@ -108,7 +108,7 @@ Added
 """""
 
 - ``pre-commit-config`` to maintain code quality using black and other useful tools.
-- Docs for integration and usage in `getting_started.rst`_.
+- Docs for integration and usage in :doc:`getting_started`
 - Tox for testing on `py{37}-django{20,21,22}`.
 - Travis CI for testing builds.
 

README.rst

@@ -12,45 +12,47 @@ django-phone-verify
     :alt: License
 
 .. image:: https://static.pepy.tech/badge/django-phone-verify?period=total&units=international_system&left_color=black&right_color=darkgreen&left_text=Downloads
-   :target: https://pepy.tech/project/django-phone-verify
+    :target: https://pepy.tech/project/django-phone-verify
 
 .. image:: https://img.shields.io/badge/Made%20with-Python-1f425f.svg
-   :target: https://www.python.org/
+    :target: https://www.python.org/
 
 .. image:: https://img.shields.io/badge/Maintained%3F-yes-green.svg
-   :target: https://GitHub.com/CuriousLearner/django-phone-verify/graphs/commit-activity
+    :target: https://GitHub.com/CuriousLearner/django-phone-verify/graphs/commit-activity
 
 .. image:: https://badge.fury.io/py/django-phone-verify.svg
-   :target: https://pypi.python.org/pypi/django-phone-verify/
+    :target: https://pypi.python.org/pypi/django-phone-verify/
 
 .. image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
-   :target: http://makeapullrequest.com
+    :target: http://makeapullrequest.com
 
 
-A Django app to support phone number verification using the security code sent via SMS.
+``django-phone-verify`` is a Django app that enables simple phone number verification using a security code sent via SMS.
+It supports Twilio and Nexmo (Vonage) out of the box and is fully customizable to suit your backend needs.
 
-Salient Features
-----------------
+Docs are available at `https://www.sanyamkhurana.com/django-phone-verify/ <https://www.sanyamkhurana.com/django-phone-verify/>`_.
 
-- Let's devs verify phone numbers via SMS.
-- Extensibility to provide tokens with varying lengths.
-- Comes with Twilio and Nexmo already integrated.
-- Set expiration time on tokens.
-- Provides an interface for writing custom SMS sending backend for easy extensibility.
-- Does not mess up with existing ``AUTH_USER_MODEL`` at all.
-- Can be used for several potential use-cases, and not just auth.
-- Provides ready endpoints for sending SMS and verification (See `api_endpoints.rst`_).
+Features
+--------
 
-.. _api_endpoints.rst: https://github.com/CuriousLearner/django-phone-verify/blob/master/phone_verify/docs/api_endpoints.rst
+- 🔐 Verify phone numbers using SMS security codes
+- 🔧 Supports custom token length and expiration time
+- 🔄 Built-in support for Twilio and Nexmo (Vonage)
+- 🧩 Easily extensible via pluggable backends
+- ✅ Doesn't interfere with your existing ``AUTH_USER_MODEL``
+- 🚀 Ready-to-use API endpoints via Django REST Framework
+- 🛠 Can be used for multiple flows like signup, 2FA, marketing opt-in, etc.
 
 Installation
 ------------
 
+Install the package with all supported backends:
+
 .. code-block:: shell
 
     pip install django-phone-verify[all]
 
-You also have option to install only the required dependencies for Twilio or Nexmo:
+Or install with just the backend you need:
 
 .. code-block:: shell
 
@@ -60,27 +62,22 @@ You also have option to install only the required dependencies for Twilio or Nex
 Configuration
 -------------
 
-- Add app to `INSTALLED_APPS`
+1. Add ``phone_verify`` to ``INSTALLED_APPS``:
 
 .. code-block:: python
 
-    # In settings.py:
-
-    # Add app to `INSTALLED_APPS`
     INSTALLED_APPS = [
         ...
         "phone_verify",
         ...
     ]
 
-- Add settings for Phone Verify as you desire:
+2. Configure ``PHONE_VERIFICATION`` settings:
 
 .. code-block:: python
 
-    # In settings.py
-    # Add settings for phone_verify to work
     PHONE_VERIFICATION = {
-        "BACKEND": "phone_verify.backends.twilio.TwilioBackend",
+        "BACKEND": "phone_verify.backends.twilio.TwilioBackend",  # or NexmoBackend
         "OPTIONS": {
             "SID": "fake",
             "SECRET": "fake",
@@ -90,38 +87,53 @@ Configuration
         "TOKEN_LENGTH": 6,
         "MESSAGE": "Welcome to {app}! Please use security code {security_code} to proceed.",
         "APP_NAME": "Phone Verify",
-        "SECURITY_CODE_EXPIRATION_TIME": 3600,  # In seconds only
-        "VERIFY_SECURITY_CODE_ONLY_ONCE": False,  # If False, then a security code can be used multiple times for verification
+        "SECURITY_CODE_EXPIRATION_TIME": 3600,  # in seconds
+        "VERIFY_SECURITY_CODE_ONLY_ONCE": False,
     }
 
+**Note:** To use Nexmo instead of Twilio, change the ``BACKEND`` path to:
+
+.. code-block:: python
+
+    "BACKEND": "phone_verify.backends.nexmo.NexmoBackend"
+
+and in ``OPTIONS``, use:
+
+.. code-block:: python
+
+    "KEY": "your-nexmo-key",
+    "SECRET": "your-nexmo-secret"
+
 Usage
 -----
 
-- To explore more about how to use, integrate and leverage the existing functionality of ``Django Phone Verify``, have a look at `getting_started.rst`_
+To get started using the app and integrating it into your own flow (DRF or non-DRF), check the following documentation:
 
-.. _getting_started.rst: https://github.com/CuriousLearner/django-phone-verify/blob/master/docs/getting_started.rst
-
-**Note**: ``Django Phone Verify`` also provides ``Nexmo`` as a backend service other than ``Twilio``. To switch to ``Nexmo``, replace ``BACKEND`` within your ``PHONE_VERIFICATION`` setting with ``phone_verify.backends.nexmo.NexmoBackend`` and define ``KEY`` within ``OPTIONS`` of ``PHONE_VERIFICATION`` setting, with your Nexmo API key, in place of already available ``SID``.
+- 📘 `Getting Started Guide <docs/getting_started.rst>`_
+- 🔌 `Integration Examples <docs/integration.rst>`_
+- ⚙️ `Custom Backend Guide <docs/customization.rst>`_
+- 📮 `API Endpoints Reference <phone_verify/docs/api_endpoints.rst>`_
 
 Compatibility
 -------------
+
 - Python 3.6+
 - Django 2.1+
 - Django REST Framework 3.9+
 
 Contributing
 ------------
 
-No code is bug-free and I'm sure this app will have bugs. If you find any bugs, please create an issue on GitHub.
+Found a bug? Want to suggest an improvement or submit a patch?
+Pull requests are welcome! 🙌 Please check the `contributing guide <https://github.com/CuriousLearner/django-phone-verify/blob/master/docs/contributing.rst>`_ before you start.
 
-Licence
+License
 -------
 
-GPLv3
+This project is licensed under the **GPLv3** license.
 
 Changelog
 ---------
 
-See `changelog.rst`_
-
-.. _changelog.rst: https://github.com/CuriousLearner/django-phone-verify/blob/master/CHANGELOG.rst
+See the full changelog here:
+📄 `CHANGELOG.rst <https://github.com/CuriousLearner/django-phone-verify/blob/master/CHANGELOG.rst>`_

docs/changelog.rst

@@ -0,0 +1,2 @@
+.. include:: ../CHANGELOG.rst
+   :start-line: 0

docs/contributing.rst

@@ -1,73 +1,94 @@
 Contributing
 ============
 
-Thank you for your interest in contributing to this project. The following set of steps should help you get started with contributing to ``django-phone-verify``.
+Thank you for your interest in contributing to ``django-phone-verify``!
+The following guide will help you set up your development environment and start contributing effectively.
 
 Project Setup
 -------------
 
-1. Clone the git repository for this project onto your local system.
+1. **Clone the repository**
 
-::
+   Clone the GitHub repository to your local system:
 
-    git clone https://github.com/CuriousLearner/django-phone-verify.git
+   .. code-block:: shell
 
-2. Create a virtual environment. You may use any tool of your choice.
+       git clone https://github.com/CuriousLearner/django-phone-verify.git
 
-::
+2. **Create and activate a virtual environment**
 
-    $ python3 -m venv venv
+   You may use any tool of your choice (e.g., ``venv`` or ``virtualenv``). Here’s how to do it using the built-in ``venv``:
 
-Activate env using
+   .. code-block:: shell
 
-::
+       python3 -m venv venv
+       source venv/bin/activate
 
-    $ source venv/bin/activate
+3. **Install development dependencies**
 
-3. Install the python dependencies via the following command. Make sure you are in the root directory.
+   Make sure you are in the root directory of the project, then install the required dependencies:
 
-::
+   .. code-block:: shell
 
-    (venv) $ python -m pip install -r requirements/development.txt
+       python -m pip install -r requirements/development.txt
 
-That's it! You now have a local setup of ``django-phone-verify``. You can start contributing to it.
+You now have a local setup of ``django-phone-verify`` ready for development and contribution.
 
+.. _running-tests:
 
 Running Tests
 -------------
 
-``django-phone-verify`` has unit tests located in the ``tests/`` directory. The project uses ``pytest`` to write and run the tests.
+Unit tests are located in the ``tests/`` directory, and the project uses ``pytest`` for testing.
 
-Before we proceed with performing tests, we should install the testing dependencies. Install the testing requirements via the following command. Make sure you are in the root directory.
+1. **Install testing dependencies**
 
-::
+   From the root directory, run:
 
-    (venv) $ python -m pip install requirements/testing.txt
+   .. code-block:: shell
 
-To run the test, you have to run the ``pytest`` command. If you want to get the code coverage, use the ``--cov`` argument as
+       python -m pip install -r requirements/testing.txt
 
-::
+2. **Run the test suite**
 
-    (venv) $ pytest --cov
+   To execute the test suite:
 
-This will list down the current code coverage.
+   .. code-block:: shell
 
-To test your changes with different versions of Python & Django that the project supports, you can use ``tox`` like:
+       pytest
 
-::
+3. **Run tests with code coverage**
 
-    (venv) $ tox
+   For checking code coverage, use the ``--cov`` option:
 
-This would run all the tests with a combination of all Python/Django versions that it supports. Check the ``tox.ini`` file at the root of the project for more details.
+   .. code-block:: shell
 
-Local Development and testing
+       pytest --cov
+
+4. **Test with multiple Python/Django versions using tox**
+
+   The project supports multiple versions of Python and Django. To run the full test matrix using ``tox``, use:
+
+   .. code-block:: shell
+
+       tox
+
+   Refer to the ``tox.ini`` file at the root of the repository for supported versions and configurations.
+
+Local Development and Testing
 -----------------------------
 
-Once you've made code changes, you can install this local development copy of the Django app in your project by using the ``-e`` flag with ``pip install`` in the following manner:
+After making code changes, you can install the app in **editable mode** inside your Django project to test your modifications:
+
+.. code-block:: shell
+
+    cd /path/to/your/django/project
+    pip install -e /path/to/local/django-phone-verify
+
+This installs your local copy instead of the one from PyPI, allowing you to test changes immediately.
 
-::
+Once you're satisfied, refer back to the :ref:`running-tests` section to verify that everything works correctly before submitting a pull request.
 
-    $ cd /path/to/new/django/project
-    $ pip install -e /path/to/local/django-phone-verify
+----
 
-This will install your local modified copy of the app in your Django application rather than fetching it from PyPI. After you're satisfied with the changes, you can run tests using the `running tests <#running-tests>`_ section above.
+Feel free to open issues, suggest improvements, and submit pull requests. Happy coding!