Added documentation (#19)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
tj-django · May 27, 2021 · 5b9dd4e · 5b9dd4e
1 parent ef58a45
commit 5b9dd4e
Show file tree

Hide file tree

Showing 21 changed files with 212 additions and 192 deletions.
diff --git a/.github/workflows/update-doc-assets.yml b/.github/workflows/update-doc-assets.yml
@@ -0,0 +1,57 @@
+name: Sync doc assets
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  sync-doc-assets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2.3.4
+        with:
+          fetch-depth: 0
+
+      - name: Run test
+        uses: tj-actions/remark@v1.5
+
+      - name: Verify Changed files
+        uses: tj-actions/verify-changed-files@v6
+        id: verify_changed_files
+        with:
+          files: |
+            README.md
+
+      - name: README.md changed
+        if: steps.verify_changed_files.outputs.files_changed == 'true'
+        run: |
+          echo "README.md has uncommited changes"
+          exit 1
+
+      - name: Create Pull Request
+        if: failure()
+        uses: peter-evans/create-pull-request@v3
+        with:
+          base: "main"
+          title: "Updated README.md"
+          branch: "chore/update-readme"
+          commit-message: "Updated README.md"
+          body: "Updated README.md"
+          token: ${{ secrets.PAT_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.6.x'
+
+      - name: Upgrade pip
+        run: |
+          pip install -U pip
+
+      - name: Install dependencies
+        run: make install-docs
+
+      - name: Deploy to github pages
+        run: |
+          make github-pages
diff --git a/.gitignore b/.gitignore
@@ -112,3 +112,5 @@ ENV/
 *.db
 
 *.sqlite3
+
+site/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -5,16 +5,22 @@ repos:
       - id: autoflake
         args: ['--in-place', '--remove-all-unused-imports', '--remove-unused-variable']
 
-  -   repo: https://github.com/pre-commit/pre-commit-hooks
-      rev: v4.0.1
-      hooks:
-        - id: trailing-whitespace
-          exclude: ^docs/.*|.*.md
-        - id: end-of-file-fixer
-          exclude: ^docs/.*|.*.md
+  - repo: https://github.com/pycqa/isort
+    rev: 5.6.4
+    hooks:
+      - id: isort
+        args: ["--profile", "black", "--filter-files"]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^docs/.*|.*.md
+      - id: end-of-file-fixer
+        exclude: ^docs/.*|.*.md
 
-  -   repo: https://github.com/psf/black
-      rev: 21.5b1
-      hooks:
-        - id: black
-          language_version: python3
+  - repo: https://github.com/psf/black
+    rev: 21.5b1
+    hooks:
+      - id: black
+        language_version: python3
diff --git a/Makefile b/Makefile
@@ -58,16 +58,11 @@ coverage:  ## check code coverage quickly with the default Python
 	@coverage html
 	@$(BROWSER) htmlcov/index.html
 
-docs: install-docs  ## generate Sphinx HTML documentation, including API docs
-	@rm -f docs/django_migration_fixer.rst
-	@rm -f docs/modules.rst
-	@sphinx-apidoc -o docs/ restricted_fields
-	@$(MAKE) -C docs clean
-	@$(MAKE) -C docs html
-	@$(BROWSER) docs/_build/html/index.html
-
-servedocs: docs  ## compile the docs watching for changes
-	@watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D restricted_fields docs
+github-pages: install-docs
+	@DJANGO_SETTINGS_MODULE=django_migration_fixer.settings portray on_github_pages
+
+servedocs: install-docs  ## compile the docs watching for changes
+	@DJANGO_SETTINGS_MODULE=django_migration_fixer.settings portray in_browser
 
 release: dist  ## package and upload a release
 	@twine upload dist/*

diff --git a/README.md b/README.md
@@ -1,18 +1,15 @@
-[![PyPI](https://img.shields.io/pypi/v/django-migration-fixer)](https://pypi.python.org/pypi/django-migration-fixer) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/1e607eb508f64cefad18f50d6ff920cf)](https://www.codacy.com/gh/tj-django/django-migration-fixer/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=tj-django/django-migration-fixer&amp;utm_campaign=Badge_Grade) [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/1e607eb508f64cefad18f50d6ff920cf)](https://www.codacy.com/gh/tj-django/django-migration-fixer/dashboard?utm_source=github.com&utm_medium=referral&utm_content=tj-django/django-migration-fixer&utm_campaign=Badge_Coverage) [![codecov](https://codecov.io/gh/tj-django/django-migration-fixer/branch/main/graph/badge.svg?token=peNs0PpfP6)](https://codecov.io/gh/tj-django/django-migration-fixer) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI](https://img.shields.io/pypi/v/django-migration-fixer)](https://pypi.python.org/pypi/django-migration-fixer) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/1e607eb508f64cefad18f50d6ff920cf)](https://www.codacy.com/gh/tj-django/django-migration-fixer/dashboard?utm_source=github.com\&utm_medium=referral\&utm_content=tj-django/django-migration-fixer\&utm_campaign=Badge_Grade) [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/1e607eb508f64cefad18f50d6ff920cf)](https://www.codacy.com/gh/tj-django/django-migration-fixer/dashboard?utm_source=github.com\&utm_medium=referral\&utm_content=tj-django/django-migration-fixer\&utm_campaign=Badge_Coverage) [![codecov](https://codecov.io/gh/tj-django/django-migration-fixer/branch/main/graph/badge.svg?token=peNs0PpfP6)](https://codecov.io/gh/tj-django/django-migration-fixer) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-migration-fixer)](https://pypi.python.org/pypi/django-migration-fixer) [![PyPI - Django Version](https://img.shields.io/pypi/djversions/django-migration-fixer)](https://pypi.python.org/pypi/django-migration-fixer) [![Downloads](https://pepy.tech/badge/django-migration-fixer/month)](https://pepy.tech/project/django-migration-fixer)
 
 [![Test](https://github.com/tj-django/django-migration-fixer/actions/workflows/test.yml/badge.svg)](https://github.com/tj-django/django-migration-fixer/actions/workflows/test.yml) [![Upload Python Package](https://github.com/tj-django/django-migration-fixer/actions/workflows/deploy.yml/badge.svg)](https://github.com/tj-django/django-migration-fixer/actions/workflows/deploy.yml) [![Run linters](https://github.com/tj-django/django-migration-fixer/actions/workflows/lint.yml/badge.svg)](https://github.com/tj-django/django-migration-fixer/actions/workflows/lint.yml)
 
-
-
 # django-migration-fixer
 
 ## Problem
 
 Maintain a linear migration history when conflicts occur as a result of changes made using different versions of the default branch.
 
-
 ### Example
 
 **Branch:** `main`
@@ -26,7 +23,6 @@ Maintain a linear migration history when conflicts occur as a result of changes
 
 ```
 
-
 **Branch:** `feature/test-a`
 
 ```bash
@@ -51,9 +47,7 @@ Maintain a linear migration history when conflicts occur as a result of changes
 
 ```
 
-
-Both `feature/test-a` and `feature/test-b` share the last migration on `main` (`0002_auto_20210521_2328.py`) 
-
+Both `feature/test-a` and `feature/test-b` share the last migration on `main` (`0002_auto_20210521_2328.py`)
 
 Once `feature/test-a` is merged into `main` you run into the problem of resolving migrations on `feature/test-b` which was dependent on `0002_auto_20210521_2328.py`
 
@@ -82,24 +76,20 @@ Once `feature/test-a` is merged into `main` you run into the problem of resolvin
 
 ```
 
-
 Running [`makemigrations`](https://docs.djangoproject.com/en/3.2/ref/django-admin/#django-admin-makemigrations) fails with the following error:
 
-```
-CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph: (0003_auto_20210522_1128, 0003_auto_20210522_1228 in app).
-To fix them run 'python manage.py makemigrations --merge'
-```
+    CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph: (0003_auto_20210522_1128, 0003_auto_20210522_1228 in app).
+    To fix them run 'python manage.py makemigrations --merge'
 
 Using the `--merge` option creates a new migration file which might not be desired.
 
-
 ## Solution
 
 `django-migration-fixer` identifies changes between the default branch `main`, and the feature branch `feature/test-b` and maintains a linear dependency history as shown below:
 
 Run
 
-```bash script
+```bash
 $ python manage.py makemigrations --fix
 ```
 
@@ -118,9 +108,8 @@ $ python manage.py makemigrations --fix
 
 `0004_auto_20210522_1228.py`
 
-```python
-# Generated by Django 3.2.3 on 2021-05-24 12:43
-
+```py
+...
 from django.db import migrations, models
 
 
@@ -135,57 +124,57 @@ class Migration(migrations.Migration):
     ]
 ```
 
-
 > NOTE: :warning:
-> * This also works when there are conflicts detected on the default branch. 
-> 
->   i.e You can run `python manage.py makemigrations --fix` on the `main` branch.
->  
->   Which relies on primitively picking the first migration file
->   e.g `(0003_auto_20210522_1128, 0003_auto_20210522_1228 in app)`
->   would result in `0003_auto_20210522_1128.py` being picked as the 
->   base migration which might not be accurate in every case and is not recommended.
+>
+> *   This also works when there are conflicts detected on the default branch.
+>
+>     i.e You can run `python manage.py makemigrations --fix` on the `main` branch.
+>
+>     Which relies on primitively picking the first migration file
+>     e.g `(0003_auto_20210522_1128, 0003_auto_20210522_1228 in app)`
+>     would result in `0003_auto_20210522_1128.py` being picked as the
+>     base migration which might not be accurate in every case and is not recommended.
 
 ### Assumptions
 
 The final migration on the default branch would be used as the base for all subsequent migrations.
 
-
 ## Installation
 
-```bash script
+```bash
 $ pip install django-migration-fixer
 ```
 
 #### Add `migration_fixer` to your INSTALLED_APPS
 
 ```python
+
 INSTALLED_APPS = [
     ...,
     "migration_fixer",
     ...,
 ]
-```
 
+```
 
 ## Usage
 
-```bash script
-$ python manage.py makemigrations --fix 
+```bash
+$ python manage.py makemigrations --fix
 ```
 
 ### Specifying a different default branch name
 
 Use:
 
-```bash script
-$ python manage.py makemigrations -b master --fix 
+```bash
+$ python manage.py makemigrations -b master --fix
 ```
 
-
 ## Features
-- Resolves migration conflicts on feature/PR branches
-- Resolves migration conflicts on the default branch **(NOT RECOMMENDED)**
-- Supports numbered migration modules i.e (`0001_....py`)
-- Supports named migration modules i.e (`custom_migration.py`)
-- Re-index all migrations using the last migration on the default branch i.e `main`
+
+*   Resolves migration conflicts on feature/PR branches
+*   Resolves migration conflicts on the default branch **(NOT RECOMMENDED)**
+*   Supports numbered migration modules i.e (`0001_....py`)
+*   Supports named migration modules i.e (`custom_migration.py`)
+*   Re-index all migrations using the last migration on the default branch i.e `main`
diff --git a/django_migration_fixer/settings.py b/django_migration_fixer/settings.py
@@ -15,62 +15,38 @@
 # Build paths inside the project like this: os.path.join(BASE_DIR, ...)
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
-
 # Quick-start development settings - unsuitable for production
 # See https://docs.djangoproject.com/en/2.2/howto/deployment/checklist/
 
 # SECURITY WARNING: keep the secret key used in production secret!
 SECRET_KEY = "ljq%0159d51t&5&)-*ii6dudczbu(eq(5qda7qjg(qp@#4#vun"
 
-# SECURITY WARNING: don't run with debug turned on in production!
-DEBUG = True
-
-ALLOWED_HOSTS = []
-
-
-# Application definition
-
-INSTALLED_APPS = [
-    "django.contrib.admin",
-    "django.contrib.auth",
-    "django.contrib.contenttypes",
-    "django.contrib.sessions",
-    "django.contrib.messages",
-    "django.contrib.staticfiles",
-    "migration_fixer",
-    "demo",
-]
-
 MIDDLEWARE = [
     "django.middleware.security.SecurityMiddleware",
-    "django.contrib.sessions.middleware.SessionMiddleware",
     "django.middleware.common.CommonMiddleware",
-    "django.middleware.csrf.CsrfViewMiddleware",
     "django.contrib.auth.middleware.AuthenticationMiddleware",
-    "django.contrib.messages.middleware.MessageMiddleware",
     "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
 
-ROOT_URLCONF = "django_migration_fixer.urls"
-
 TEMPLATES = [
     {
         "BACKEND": "django.template.backends.django.DjangoTemplates",
         "DIRS": [],
         "APP_DIRS": True,
-        "OPTIONS": {
-            "context_processors": [
-                "django.template.context_processors.debug",
-                "django.template.context_processors.request",
-                "django.contrib.auth.context_processors.auth",
-                "django.contrib.messages.context_processors.messages",
-            ],
-        },
     },
 ]
 
-WSGI_APPLICATION = "django_migration_fixer.wsgi.application"
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = True
+
+# Application definition
 
+INSTALLED_APPS = [
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "migration_fixer",
+    "demo",
+]
 
 # Database
 # https://docs.djangoproject.com/en/2.2/ref/settings/#databases
@@ -81,42 +57,3 @@
         "NAME": os.path.join(BASE_DIR, "db.sqlite3"),
     }
 }
-
-
-# Password validation
-# https://docs.djangoproject.com/en/2.2/ref/settings/#auth-password-validators
-
-AUTH_PASSWORD_VALIDATORS = [
-    {
-        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
-    },
-]
-
-
-# Internationalization
-# https://docs.djangoproject.com/en/2.2/topics/i18n/
-
-LANGUAGE_CODE = "en-us"
-
-TIME_ZONE = "UTC"
-
-USE_I18N = True
-
-USE_L10N = True
-
-USE_TZ = True
-
-
-# Static files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/2.2/howto/static-files/
-
-STATIC_URL = "/static/"