docs: rework documentation

README.md

@@ -35,48 +35,26 @@
 
 A tool to help upgrade Django projects to newer version of the framework by automatically fixing deprecations.
 
-## Installation
+## The problem
 
-Install via pip (or your favourite installer):
+When maintaining a Django site, over time you'll find yourself to a point where you'll need to update to the next major version of Django. When Django APIs changes, functions move or are removed, changing usages in your project might add up to many changes. Often these changes are simple to do, but sometimes a simple "find and replace" is not possible.
 
-`pip install django-codemod`
+Take, for instance, the removal of the `url()` function from Django 4.0, to be replaced by `re_path()`. In simple cases, you might even want to switch to `path()`, which has a nicer API. A typical Django project easily has 100's or routes, so this simple decision becomes a much longer task when to be made for each of them.
 
-## Usage
+### This solution
 
-2 main workflow are supported:
+This project solves this problem by providing codemodders for simple changes like this. A codemodder re-writes your code from the old way to the new way.
 
-- Prepare future upgrades by modifying code which is deprecated in a given version using the `deprecated-in` option
-- Fix previous deprecated code which is removed in a given version using the `removed-in` option
+With the help of AST analysis, we're able to understand what modifications are applicable, remove imports as they become irrelevant, and add missing ones as they are needed.
 
-**1. Deprecations**
+To continue the example, the tool will look at the route in the `url()` call, and decide whether the regular expression may be replaced by one of the built-in URL converters and use `path()` or stick to a regex and use `re_path()`.
 
-Let's say you just updated to Django 3.0, and suddenly you're flooded with deprecations warning on your CI (you have warning enabled on CI, right?).
+Interested? Check out [the documentation](https://django-codemod.readthedocs.io) for usage and the full list of codemodders.
 
-You want to resolve them to avoid missing another important warning. You can do so by running the following command from the root of your repo:
+### What this tool is not
 
-```bash
-djcodemod run --deprecated-in 3.0 {source_file_or_directory}
-```
-
-**2. Removals**
-
-This is more of a just in time operation, assuming you haven't kept up to date with deprecation warnings, and right before upgrading to a given version (let's assume Django 4.0). In this case, you should be running:
-
-```bash
-djcodemod run --removed-in 4.0 {source_file_or_directory}
-```
-
-### Explanations
-
-In either case, the tool will run for a few minutes and apply a set of modifications to your code to fix deprecated or removed usages of Django. This should be much faster than doing it manually and much robust than a simple find & replace.
-
-Check out the [documentation](https://django-codemod.readthedocs.io) for more detail on usage and the full list of codemodders.
-
-## How it works
-
-This is based on [libCST](https://libcst.readthedocs.io/en/latest/index.html) and implements codemods for it. This is currently very limited but the aim is to add more for helping with upcoming deprecations.
-
-Not finding what you need? I'm open to contributions, please send me a pull request.
+- This tool is best suited for Django sites, NOT for reusable Django applications. The project needs to target a single Django version, e.g. 3.1.x.
+- You do NOT need to install this tool as part of your project dependencies, it is a CLI tool, not a Django package to be installed in your site.
 
 ## Contributors ✨
 

docs/codemods.md

@@ -1,6 +1,6 @@
 (list_of_codemodders)=
 
-# List of codemodders
+# Codemodders
 
 Here is the list of automatic fixes which are supported by `django-codemod`
 at this stage. This list will be updated as new fixes are implemented.

docs/index.md

@@ -3,6 +3,22 @@
 A tool to help upgrade Django projects to newer version of the framework
 by automatically fixing deprecations.
 
+**The problem**
+
+When maintaining a Django site, over time you'll find yourself to a point where you'll need to update to the next major version of Django. When Django APIs changes, functions move or are removed, changing usages in your project might add up to many changes. Often these changes are simple to do, but sometimes a simple "find and replace" is not possible.
+
+Take, for instance, the removal of the `url()` function from Django 4.0, to be replaced by `re_path()`. In simple cases, you might even want to switch to `path()`, which has a nicer API. A typical Django project easily has 100's or routes, so this simple decision becomes a much longer task when to be made for each of them.
+
+**This solution**
+
+This project solves this problem by providing codemodders for simple changes like this. A codemodder re-writes your code from the old way to the new way.
+
+With the help of AST analysis, we're able to understand what modifications are applicable, remove imports as they become irrelevant, and add missing ones as they are needed.
+
+To continue the example, the tool will look at the route in the `url()` call, and decide whether the regular expression may be replaced by one of the built-in URL converters and use `path()` or stick to a regex and use `re_path()`.
+
+Interested? Check out the next sections for {ref}`installation <installation>` and {ref}`usage <usage>`.
+
 ```{toctree}
 :caption: User Guide
 :maxdepth: 2

docs/installation.md

@@ -1,35 +1,22 @@
-# Installation
+(installation)=
 
-## Stable release
+# Installation
 
-To install Django Codemod, run this command in your terminal:
+Django Codemod requires Python 3.6 or above. The preferred way to install Django Codemod, is with [pipx]:
 
 ```shell
-$ pip install django-codemod
+$ pips install django-codemod
 ```
 
-This is the preferred method to install Django Codemod, as it will always install the most recent stable release.
-
-If you don't have [pip](https://pip.pypa.io) installed, this [Python installation guide](http://docs.python-guide.org/en/latest/starting/installation/) can guide you through the process.
-
-## From sources
+It will install the latest stable release in an isolated virtual environment, hence not polluting your global Python with dependencies.
 
-The sources for Django Codemod can be downloaded from the [Github repo](https://github.com/browniebroke/django-codemod).
+If you don't have [pipx] installed, checkout [their installation instructions][pipx-install] for your operating system of choice.
 
-You can either clone the public repository:
-
-```shell
-$ git clone git://github.com/browniebroke/django-codemod
-```
+## Other ways to install
 
-Or download the [tarball](https://github.com/browniebroke/django-codemod/tarball/main):
+Django Codemod [is published on PyPI][pypi], and is based on [libCST], therefore you may install it with `pip`, `poetry` or `pipenv` if you wish to.
 
-```shell
-$ curl -OJL https://github.com/browniebroke/django-codemod/tarball/main
-```
-
-Once you have a copy of the source, you can install it with:
-
-```shell
-$ python setup.py install
-```
+[pipx]: https://pipxproject.github.io/pipx/
+[pipx-install]: https://pipxproject.github.io/pipx/installation/
+[pypi]: https://pypi.org/project/django-codemod/
+[libcst]: https://libcst.readthedocs.io

docs/usage.md

@@ -1,3 +1,5 @@
+(usage)=
+
 # Usage
 
 This package provides a `djcodemod` command line tool with 2 main supported workflows:
@@ -25,19 +27,29 @@ This is more of a just in time operation, assuming you haven't kept up to date w
 djcodemod run --removed-in 4.0 {source_file_or_directory}
 ```
 
-### Mix and match
+### Files considered
+
+The tool will only consider Python files under the given source path, ignoring files which are not tracked in git, according to rules listed in the `.gitignore` file.
+
+## Mix and match
 
 Both `--deprecated-in` and `--removed-in` can be passed at once, and both accept multiple repetitions. You can also give as many source files or directory paths as you want. A more complex example might look like this:
 
 ```bash
 djcodemod run --deprecated-in 3.0 --deprecated-in 3.1 --removed-in 2.2 example example1 example2/models.py settings.py
 ```
 
-## Next steps
+## Only run a specific codemodder
 
-In either case, the tool will take a few minutes and apply a set of modifications to your code to fix deprecated or removed usages of Django. This should be much faster than doing it manually and much robust than a simple find & replace.
+You may also run just some specific codemodders with the `--codemod` option (it can be repeated too):
 
-For the list of possible codemodders, you may use the `list` subcommand or check {ref}`the next section <list_of_codemodders>`.
+```bash
+djcodemod run --codemod URLTransformer urls.py
+```
+
+## List codemodders
+
+For the list of all possible codemodders, you may use the `list` subcommand or check {ref}`the next section <list_of_codemodders>`.
 
 ```bash
 > djcodemod list
@@ -48,7 +60,3 @@ For the list of possible codemodders, you may use the `list` subcommand or check
 │ ...                 │           ... │        ... │                                                            │
 └─────────────────────┴───────────────┴────────────┴────────────────────────────────────────────────────────────┘
 ```
-
-## Files included for codemodding
-
-The tool will only consider Python files under the given source path, ignoring files which are not tracked in git, according to rules listed in the `.gitignore` file.