It is quite rare to find legacy code with good documentation. Even if you do, the documentation might be out of sync with the code in subtle ways that can lead to further issues. Often, the best guide to understand the application's functionality is the executable test cases and the code itself.
The official Django documentation has been organized by versions at https://docs.djangoproject.com. On any page, you can quickly switch to the corresponding page in the previous versions of Django with a selector on the bottom right-hand section of the page:
In the same way, documentation for any Django package hosted on readthedocs.org can also be traced back to its previous versions. For example, you can select the documentation of django-braces
all the way back to v1.0.0 by clicking on the selector on the bottom left-hand section of the page:
Most people find it easier to understand an application if you show them a high-level diagram. While this is ideally created by someone who understands the workings of the application, there are tools that can create very helpful high-level depiction of a Django application.
A graphical overview of all models in your apps can be generated by the graph_models
management command, which is provided by the django-command-extensions
package. As shown in the following diagram, the model classes and their relationships can be understood at a glance:
This visualization is actually created using PyGraphviz. This can get really large for projects of even medium complexity. Hence, it might be easier if the applications are logically grouped and visualized separately.
PyGraphviz Installation and Usage
If you find the installation of PyGraphviz challenging, then don't worry, you are not alone. Recently, I faced numerous issues while installing on Ubuntu, starting from Python 3 incompatibility to incomplete documentation. To save your time, I have listed the steps that worked for me to reach a working setup.
On Ubuntu, you will need the following packages installed to install PyGraphviz:
$ sudo apt-get install python3.4-dev graphviz libgraphviz-dev pkg-config
Now activate your virtual environment and run pip to install the development version of PyGraphviz directly from GitHub, which supports Python 3:
$ pip install git+http://github.com/pygraphviz/pygraphviz.git#egg=pygraphviz
Next, install django-extensions
and add it to your INSTALLED_APPS
. Now, you are all set.
Here is a sample usage to create a GraphViz dot file for just two apps and to convert it to a PNG image for viewing:
$ python manage.py graph_models app1 app2 > models.dot $ dot -Tpng models.dot -o models.png