Add documentation to the project

Documentation is hosted on readthedocs.org, it’s free for public
open-source project and a popular choice.
The Sphinx readthedocs theme was picked for the same reasons.

The code examples are verified with doctest.

Most documentation for the fields live in the code directly, in an
attempt to keep them in sync.

.github/workflows/check.yml

@@ -14,6 +14,7 @@ jobs:
       matrix:
         tox-environment:
           - black
+          - doctest
           - flake8
           - isort
     env:

.readthedocs.yaml

@@ -0,0 +1,11 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+sphinx:
+  fail_on_warning: yes

README.rst

@@ -12,109 +12,12 @@ phone numbers. ``python-phonenumbers`` is a port of Google's `libphonenumber`_ l
 powers Android's phone number handling.
 
 .. _`python-phonenumbers`: https://github.com/daviddrysdale/python-phonenumbers
-.. _`libphonenumber`: https://code.google.com/p/libphonenumber/
+.. _`libphonenumber`: https://github.com/google/libphonenumber
 
-Included are:
-
-* ``PhoneNumber``, a pythonic wrapper around ``python-phonenumbers``' ``PhoneNumber`` class
-* ``PhoneNumberField``, a model field
-* ``PhoneNumberField``, a form field
-* ``PhoneNumberField``, a serializer field
-* ``PhoneNumberPrefixWidget``, a form widget for selecting a region code and
-  entering a national number. Requires the `Babel`_ package be installed.
-* ``RegionalPhoneNumberWidget``, a form widget that uses national numbers
-  unless an international number is entered.  A ``PHONENUMBER_DEFAULT_REGION``
-  setting needs to be added to your Django settings in order to know which
-  national number format to recognize.
-
-.. _`Babel`: https://pypi.org/project/Babel/
-
-Installation
-============
-
-::
-
-    pip install django-phonenumber-field[phonenumbers]
-
-As an alternative to the ``phonenumbers`` package, it is possible to install
-the ``phonenumberslite`` package which has `a lower memory footprint
-<https://github.com/daviddrysdale/python-phonenumbers#memory-usage>`_.
-
-::
-
-    pip install django-phonenumber-field[phonenumberslite]
-
-Basic usage
-===========
-
-First, add ``phonenumber_field`` to the list of the installed apps in
-your ``settings.py`` file:
-
-.. code-block:: python
-
-    INSTALLED_APPS = [
-        ...
-        'phonenumber_field',
-        ...
-    ]
-
-Then, you can use it like any regular model field:
-
-.. code-block:: python
-
-    from phonenumber_field.modelfields import PhoneNumberField
-
-    class MyModel(models.Model):
-        name = models.CharField(max_length=255)
-        phone_number = PhoneNumberField()
-        fax_number = PhoneNumberField(blank=True)
-
-Internally, PhoneNumberField is based upon ``CharField`` and by default
-represents the number as a string of an international phonenumber in the database (e.g
-``'+41524204242'``).
-
-The object returned is a PhoneNumber instance, not a string. If strings are used to initialize it,
-e.g. via ``MyModel(phone_number='+41524204242')`` or form handling, it has to be a phone number
-with country code.
-
-Settings
-========
-
-``PHONENUMBER_DB_FORMAT``
--------------------------
-
-Store phone numbers strings in the specified format.
-
-Default: ``"E164"``.
-
-Choices:
-
-- ``"E164"``,
-- ``"INTERNATIONAL"``,
-- ``"NATIONAL"`` (requires ``PHONENUMBER_DEFAULT_REGION``),
-- ``"RFC3966"`` (requires ``PHONENUMBER_DEFAULT_REGION``).
-
-``PHONENUMBER_DEFAULT_REGION``
-------------------------------
-
-`ISO-3166-1 <https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes>`_
-two-letter country code indicating how to interpret regional phone numbers.
-
-Default: ``None``.
-
-``PHONENUMBER_DEFAULT_FORMAT``
-------------------------------
-
-String formatting of phone numbers.
-
-Default: ``"E164"``.
-
-Choices:
+Documentation
+=============
 
-- ``"E164"``,
-- ``"INTERNATIONAL"``,
-- ``"NATIONAL"``,
-- ``"RFC3966"``.
+https://django-phonenumber-field.readthedocs.io/
 
 Running tests
 =============

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     = .
+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/conf.py

@@ -0,0 +1,50 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import pathlib
+import sys
+
+current_dir = pathlib.Path(__file__).parent
+# Find current settings module for doctests.
+sys.path.insert(0, str(current_dir))
+sys.path.insert(0, str(current_dir / "ext"))
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings")
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "django-phonenumber-field"
+copyright = "2022, django-phonenumber-field"
+author = "Stefan Foulis"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "phonenumber_field_docs",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = []
+
+# -- Options for extensions --------------------------------------------------
+
+intersphinx_mapping = {
+    "django": (
+        "https://docs.djangoproject.com/en/dev/",
+        "https://docs.djangoproject.com/en/dev/_objects/",
+    ),
+    "python": ("https://docs.python.org/3/", None),
+}

docs/ext/phonenumber_field_docs.py

@@ -0,0 +1,4 @@
+def setup(app):
+    app.add_crossref_type(
+        directivename="setting", rolename="setting", indextemplate="pair: %s; setting"
+    )

docs/index.rst

@@ -0,0 +1,47 @@
+🕿 django-phonenumber-field 🕿
+=============================
+
+A `Django <https://www.djangoproject.com/>`_ library which interfaces with
+`python-phonenumbers <https://github.com/daviddrysdale/python-phonenumbers>`_
+to validate, pretty print and convert phone numbers. The python-phonenumbers
+library is a port of Google’s `libphonenumber
+<https://github.com/google/libphonenumber>`_ library, which powers Android’s
+phone number handling.
+
+Installation
+============
+
+Choosing a phonenumbers provider
+--------------------------------
+
+The `python-phonenumbers <https://github.com/daviddrysdale/python-phonenumbers>`_ library comes in `two flavors
+<https://github.com/daviddrysdale/python-phonenumbers#memory-usage>`_:
+
+.. code-block::
+
+    # Installs phonenumbers minimal metadata
+    pip install "django-phonenumber-field[phonenumberslite]"
+
+.. code-block::
+
+    # Installs phonenumbers extended features (e.g. geocoding)
+    pip install "django-phonenumber-field[phonenumbers]"
+
+Setup
+-----
+
+Add ``phonenumber_field`` to the list of the installed apps in
+your ``settings.py`` file :external+django:setting:`INSTALLED_APPS`:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # Other apps…
+        "phonenumber_field",
+    ]
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   reference

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd