Merge pull request #11 from pescheckit/build-readthedocs

Build readthedocs

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 0.0.3
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    django: "5.0.1"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 296daad79a7ab3f99c582f032e2966d1
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/custom_settings.rst.txt

@@ -0,0 +1,61 @@
+Custom Settings
+===============
+
+Django Country Kit provides custom settings for further customization of country data:
+
+- **OVERRIDE_COUNTRIES**: Allows users to override specific countries with custom data.
+- **EXCLUDE_COUNTRIES**: Allows users to exclude specific countries from the available choices.
+- **INCLUDE_COUNTRIES**: Allows users to include specific countries in the available choices.
+
+Examples
+--------
+
+OVERRIDE_COUNTRIES
+~~~~~~~~~~~~~~~~~~
+
+To override specific countries with custom data, you can define the ``OVERRIDE_COUNTRIES`` setting in your Django project's settings file. Here's an example:
+
+.. code-block:: python
+
+    # settings.py
+
+    OVERRIDE_COUNTRIES = {
+        'US': {'name': 'United States of America', 'alpha3':'USA'},
+        'GB': {'name': 'United Kingdom', 'alpha3':'GBR'},
+        'CA': {'name':'Canada', 'alpha3':'CAN'}
+        # Add more overrides as needed
+    }
+
+In this example, the names of the countries with codes 'US', 'GB', and 'CA' will be overridden with custom names.
+
+EXCLUDE_COUNTRIES
+~~~~~~~~~~~~~~~~~~
+
+To exclude specific countries from the available choices, you can define the ``EXCLUDE_COUNTRIES`` setting in your Django project's settings file. Here's an example:
+
+.. code-block:: python
+
+    # settings.py
+
+    EXCLUDE_COUNTRIES = ['US', 'GB', 'CA']
+
+In this example, the countries with codes 'US', 'GB', and 'CA' will be excluded from the available choices.
+
+INCLUDE_COUNTRIES
+~~~~~~~~~~~~~~~~~~
+
+To include specific countries in the available choices, you can define the ``INCLUDE_COUNTRIES`` setting in your Django project's settings file. Here's an example:
+
+.. code-block:: python
+
+    # settings.py
+
+    INCLUDE_COUNTRIES = {
+        'US': {'name': 'United States of America', 'alpha3':'USA'},
+        'GB': {'name': 'United Kingdom', 'alpha3':'GBR'},
+        'CA': {'name':'Canada', 'alpha3':'CAN'}
+    }
+
+In this example, only the countries with codes 'US', 'GB', and 'CA' will be included in the available choices.
+
+You can customize these settings in your Django project's settings file to tailor the country data according to your needs.

docs/build/html/_sources/development.rst.txt

@@ -0,0 +1,52 @@
+Development
+===========
+
+If you want to contribute to Django Country Kit, follow these steps to set up your development environment:
+
+1. Install pipenv if you haven't already:
+
+    .. code-block:: bash
+
+        pip install pipenv
+
+2. Clone the repository:
+
+    .. code-block:: bash
+
+        git clone https://github.com/your_username/django-country-kit.git
+
+3. Navigate to the project directory:
+
+    .. code-block:: bash
+
+        cd django-country-kit
+
+4. Install development dependencies:
+
+    .. code-block:: bash
+
+        pipenv install --dev
+
+5. Activate the virtual environment:
+
+    .. code-block:: bash
+
+        pipenv shell
+
+6. Run migrations:
+
+    .. code-block:: bash
+
+        python manage.py migrate
+
+7. Run collectstatic:
+
+    .. code-block:: bash
+
+        python manage.py collectstatic
+
+8. Start the development server:
+
+    .. code-block:: bash
+
+        python manage.py runserver

docs/build/html/_sources/index.rst.txt

@@ -0,0 +1,18 @@
+Django Country Kit Documentation
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   custom_settings
+   development
+
+Indices and Tables
+===================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/build/html/_sources/installation.rst.txt

@@ -0,0 +1,28 @@
+Installation
+============
+
+To install Django Country Kit, follow these steps:
+
+1. Install Django Country Kit using pip:
+
+    .. code-block:: bash
+
+        pip install django-country-kit
+
+2. Add `'django_country_kit'` to your `INSTALLED_APPS` in your Django project's settings:
+
+    .. code-block:: python
+
+        INSTALLED_APPS = [
+            # ...
+            'django_country_kit',
+            # ...
+        ]
+
+
+3. Run collectstatic:
+
+    .. code-block:: bash
+
+        python manage.py collectstatic
+

docs/build/html/_sources/usage.rst.txt

@@ -0,0 +1,86 @@
+Usage
+=====
+
+Django Country Kit provides the following features for usage:
+
+Country Model Field
+-------------------
+
+In your models, use the ``CountryField`` to store country codes:
+
+.. code-block:: python
+
+    from django.db import models
+    from django_country_kit.fields import CountryField
+    
+    class YourModel(models.Model):
+        country = CountryField()
+
+For multiple selections:
+
+.. code-block:: python
+
+    from django.db import models
+    from django_country_kit.fields import CountryField
+    
+    class YourModel(models.Model):
+        countries = CountryField(multiple=True)
+
+Country Widget
+---------------
+
+In your forms, use the ``CountryWidget`` to render a dropdown list of countries:
+
+.. code-block:: python
+
+    from django import forms
+    from django_country_kit.widgets import CountryWidget
+    
+    class YourForm(forms.Form):
+        country = forms.CharField(widget=CountryWidget())
+
+For multiple selections:
+
+.. code-block:: python
+
+    from django import forms
+    from django_country_kit.widgets import MultipleCountryWidget
+    
+    class YourForm(forms.Form):
+        countries = forms.CharField(widget=MultipleCountryWidget())
+
+Country Class
+--------------
+
+The ``Country`` class represents a country and provides properties for accessing its name, alpha3, and code. This class is part of the Django Country Kit and offers convenient functionality for handling country-related data.
+
+
+You can create an instance of the ``Country`` class to retrieve information about a specific country. Here's how you can use it:
+
+.. code-block:: python
+
+    from django_country_kit.base import Country
+
+    # Create a Country instance with a specific country code
+    country = Country(code='US')
+
+    # Retrieve the name of the country
+    country_name = country.name  # Returns 'United States'
+
+    # Retrieve the alpha3 code of the country
+    country_alpha3 = country.alpha3  # Returns 'USA'
+
+Or you can create by country name:
+
+.. code-block:: python
+
+    from django_country_kit.base import Country
+
+    # Create a Country instance with a country name
+    country = Country(name='United States')
+
+    # Retrieve the code of the country
+    country_name = country.code  # Returns 'United States'
+
+    # Retrieve the alpha3 code of the country
+    country_alpha3 = country.alpha3  # Returns 'USA'