From 1bc89abe6384cded622e5750a3d7d834aaefe33b Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Fri, 24 Feb 2023 01:32:28 +0530 Subject: [PATCH 1/8] chore: Build and publish docs --- .github/workflows/build-docs.yml | 24 ++++++++++++++++++++++++ docs/conf.py | 0 docs/index.rst | 0 3 files changed, 24 insertions(+) create mode 100644 .github/workflows/build-docs.yml create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..b1f0357 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,24 @@ +name: Build and Publish Docs + +on: [push, pull_request, workflow_dispatch] + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v3 + - name: Install dependencies + run: | + pip install sphinx sphinx_rtd_theme + - name: Sphinx build + run: | + sphinx-build docs _build + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _build/ + force_orphan: true diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..e69de29 From 0f726f36b1acf1791a5e101dac252a91d1f11937 Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Fri, 24 Feb 2023 01:40:14 +0530 Subject: [PATCH 2/8] add toctree for sphinx --- docs/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index e69de29..3792011 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -0,0 +1,7 @@ +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + usage.rst + how_to_write_custom_backend.rst + contributing.rst From a78b4a6ba83d7ecc0b2d1d2d53010518323858be Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Fri, 24 Feb 2023 01:42:55 +0530 Subject: [PATCH 3/8] push docs for testing --- .github/workflows/build-docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index b1f0357..8270cb7 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -16,7 +16,6 @@ jobs: sphinx-build docs _build - name: Deploy uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} From 6d6dbe18a2835e2f09efaa62faea54e039e7736c Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Fri, 24 Feb 2023 01:49:55 +0530 Subject: [PATCH 4/8] add _build in .gitignore --- .github/workflows/build-docs.yml | 1 + .gitignore | 3 +++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 8270cb7..b1f0357 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -16,6 +16,7 @@ jobs: sphinx-build docs _build - name: Deploy uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index c697e1c..27029f9 100644 --- a/.gitignore +++ b/.gitignore @@ -105,3 +105,6 @@ venv.bak/ # Editor specific .vscode/ + +# rST docs +_build/ From 81b3daa6b707f64651abd103530523d8e8cb6b3f Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Sun, 26 Feb 2023 16:47:58 +0530 Subject: [PATCH 5/8] docs: add config file for sphinx --- .github/workflows/build-docs.yml | 2 +- README.rst | 7 ++- docs/conf.py | 55 +++++++++++++++++++ ...e_custom_backend.rst => customization.rst} | 4 +- docs/{usage.rst => getting_started.rst} | 5 +- docs/index.rst | 16 +++++- 6 files changed, 79 insertions(+), 10 deletions(-) rename docs/{how_to_write_custom_backend.rst => customization.rst} (99%) rename docs/{usage.rst => getting_started.rst} (99%) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index b1f0357..f77966d 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,6 +1,6 @@ name: Build and Publish Docs -on: [push, pull_request, workflow_dispatch] +on: [workflow_dispatch] jobs: docs: diff --git a/README.rst b/README.rst index a1a02b6..24a2dfa 100644 --- a/README.rst +++ b/README.rst @@ -60,6 +60,7 @@ Configuration INSTALLED_APPS = [ ... "phone_verify", + ... ] - Add settings for Phone Verify as you desire: @@ -86,9 +87,9 @@ Configuration Usage ----- -- To explore more about how to use, integrate and leverage the existing functionality of ``Django Phone Verify``, have a look at `usage.rst`_ +- To explore more about how to use, integrate and leverage the existing functionality of ``Django Phone Verify``, have a look at `getting_started.rst`_ -.. _usage.rst: https://github.com/CuriousLearner/django-phone-verify/blob/master/docs/usage.rst +.. _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``. @@ -210,7 +211,7 @@ Added """"" - ``pre-commit-config`` to maintain code quality using black and other useful tools. -- Docs for integration and usage in `usage.rst`_. +- Docs for integration and usage in `getting_started.rst`_. - Tox for testing on `py{37}-django{20,21,22}`. - Travis CI for testing builds. diff --git a/docs/conf.py b/docs/conf.py index e69de29..1a9788a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -0,0 +1,55 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..")) + +# -- Project information ----------------------------------------------------- + +project = "Django Phone Verify" +copyright = "2017-2023, Sanyam Khurana" +author = "Sanyam Khurana" + +# The full version, including alpha/beta/rc tags +release = "3.0.0" + +master_doc = "index" + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["sphinx.ext.intersphinx", "sphinx.ext.autodoc"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "alabaster" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ["_static"] diff --git a/docs/how_to_write_custom_backend.rst b/docs/customization.rst similarity index 99% rename from docs/how_to_write_custom_backend.rst rename to docs/customization.rst index 2d25a51..91b03b5 100644 --- a/docs/how_to_write_custom_backend.rst +++ b/docs/customization.rst @@ -1,5 +1,5 @@ -How to write custom backend? -============================ +Customization +============= In case you want to use anything other than the provided backends (``phone_verify.backends.nexmo.NexmoBackend`` and ``phone_verify.backends.twilio.TwilioBackend``), you can write a custom backend by extending ``phone_verify.backends.base.BaseBackend`` as shown below. diff --git a/docs/usage.rst b/docs/getting_started.rst similarity index 99% rename from docs/usage.rst rename to docs/getting_started.rst index a2017c4..630c0dc 100644 --- a/docs/usage.rst +++ b/docs/getting_started.rst @@ -1,5 +1,5 @@ -How to Use Django Phone Verify? -=============================== +Getting Started +=============== Installation @@ -22,6 +22,7 @@ Configuration INSTALLED_APPS = [ ... 'phone_verify', + ... ] - Add settings in your ``settings.py`` file: diff --git a/docs/index.rst b/docs/index.rst index 3792011..6eeeaac 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,19 @@ +Welcome to Django Phone Verify's documentation! +=============================================== + +``Django Phone Verify`` is a simple Django app that allows you to easily add phone number verification to your project using the security code sent via SMS. + +The app uses the Twilio/Nexmo API to send verification codes via SMS and allows users to verify their phone numbers by entering the code they receive. + .. toctree:: :maxdepth: 4 :caption: Contents: - usage.rst - how_to_write_custom_backend.rst + getting_started.rst + customization.rst contributing.rst + +Indices and tables +================== + +* :ref:`search` From 99924b10fe5bb7cb07afbb3b834992422091a73c Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Sun, 26 Feb 2023 17:39:15 +0530 Subject: [PATCH 6/8] Use furo theme and arrange docs properly --- .github/workflows/build-docs.yml | 2 +- docs/conf.py | 4 ++-- docs/contributing.rst | 9 ++++++--- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index f77966d..bb3448b 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -10,7 +10,7 @@ jobs: - uses: actions/setup-python@v3 - name: Install dependencies run: | - pip install sphinx sphinx_rtd_theme + pip install sphinx sphinx_rtd_theme furo - name: Sphinx build run: | sphinx-build docs _build diff --git a/docs/conf.py b/docs/conf.py index 1a9788a..c68d122 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,7 +34,7 @@ extensions = ["sphinx.ext.intersphinx", "sphinx.ext.autodoc"] # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +# templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -47,7 +47,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "alabaster" +html_theme = "furo" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/contributing.rst b/docs/contributing.rst index b07f8d8..6a39214 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,7 +1,10 @@ +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``. Project Setup -============= +------------- 1. Clone the git repository for this project onto your local system. @@ -31,7 +34,7 @@ That's it! You now have a local setup of ``django-phone-verify``. You can start Running Tests -============= +------------- ``django-phone-verify`` has unit tests located in the ``tests/`` directory. The project uses ``pytest`` to write and run the tests. @@ -58,7 +61,7 @@ To test your changes with different versions of Python & Django that the project 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. 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: From dc76b317d9f9e3cfe127172b015aea3514d2d62d Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Mon, 27 Feb 2023 21:40:19 +0530 Subject: [PATCH 7/8] use sphinx-rtd-theme --- .github/workflows/build-docs.yml | 2 +- docs/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index bb3448b..f77966d 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -10,7 +10,7 @@ jobs: - uses: actions/setup-python@v3 - name: Install dependencies run: | - pip install sphinx sphinx_rtd_theme furo + pip install sphinx sphinx_rtd_theme - name: Sphinx build run: | sphinx-build docs _build diff --git a/docs/conf.py b/docs/conf.py index c68d122..f5b2c4b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,7 +47,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "furo" +html_theme = "sphinx_rtd_theme" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, From 10580d72b0142935b3ced5b141d8887f92bc83b4 Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Mon, 27 Feb 2023 21:51:33 +0530 Subject: [PATCH 8/8] use alabaster theme --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index f5b2c4b..60ad1c7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,7 +47,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = "alabaster" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files,