diff options
| author | Tim Schilling <schillingt@better-simple.com> | 2023-02-07 08:26:37 -0600 |
|---|---|---|
| committer | Carlton Gibson <carlton.gibson@noumenal.es> | 2023-02-07 20:22:11 +0100 |
| commit | 757c456d232279ae57546c9c39a9f81183c8a82f (patch) | |
| tree | c50ef1f8c0e7dfb4d3fe14ef1e692bf095f73043 /docs | |
| parent | e8a39da396b3ed8e469f569e4e865a54ae5dad0b (diff) | |
[4.2.x] Fixed #34146 -- Added 3rd-party lib tutorial step.
Added a tutorial step that highlights Django Debug Toolbar, on of the
most common third party packages. It also added a mention of
djangopackages.com as a place to search for other libraries and a
link to Adam Johnson’s post on evaluating whether a package is
well-maintained.
Third-party packages are one of Django’s strengths. This should give
folks a sound route in.
Backport of 7715c9fef55c8775608cdb64d5666c7f90ada937 and
1df7814e4b76211a13eaecd77a05137006b82723 from main
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.txt | 3 | ||||
| -rw-r--r-- | docs/intro/index.txt | 1 | ||||
| -rw-r--r-- | docs/intro/reusable-apps.txt | 2 | ||||
| -rw-r--r-- | docs/intro/tutorial07.txt | 11 | ||||
| -rw-r--r-- | docs/intro/tutorial08.txt | 101 | ||||
| -rw-r--r-- | docs/spelling_wordlist | 1 |
6 files changed, 108 insertions, 11 deletions
diff --git a/docs/index.txt b/docs/index.txt index bbf237bb59..f4878fc850 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -22,7 +22,8 @@ Are you new to Django or to programming? This is the place to start! :doc:`Part 4: Forms and generic views <intro/tutorial04>` | :doc:`Part 5: Testing <intro/tutorial05>` | :doc:`Part 6: Static files <intro/tutorial06>` | - :doc:`Part 7: Customizing the admin site <intro/tutorial07>` + :doc:`Part 7: Customizing the admin site <intro/tutorial07>` | + :doc:`Part 8: Adding third-party packages <intro/tutorial08>` * **Advanced Tutorials:** :doc:`How to write reusable apps <intro/reusable-apps>` | diff --git a/docs/intro/index.txt b/docs/intro/index.txt index 29462c6f9b..ca4836367f 100644 --- a/docs/intro/index.txt +++ b/docs/intro/index.txt @@ -17,6 +17,7 @@ place: read this material to quickly get up and running. tutorial05 tutorial06 tutorial07 + tutorial08 reusable-apps whatsnext contributing diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index f0fa4b1306..c3b951dfdb 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -2,7 +2,7 @@ Advanced tutorial: How to write reusable apps ============================================= -This advanced tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>` +This advanced tutorial begins where :doc:`Tutorial 8 </intro/tutorial08>` left off. We'll be turning our web-poll into a standalone Python package you can reuse in new projects and share with other people. diff --git a/docs/intro/tutorial07.txt b/docs/intro/tutorial07.txt index 35205e6119..54567fcbb5 100644 --- a/docs/intro/tutorial07.txt +++ b/docs/intro/tutorial07.txt @@ -418,12 +418,5 @@ uses a template variable called ``app_list``. That variable contains every installed Django app. Instead of using that, you can hard-code links to object-specific admin pages in whatever way you think is best. -What's next? -============ - -The beginner tutorial ends here. In the meantime, you might want to check out -some pointers on :doc:`where to go from here </intro/whatsnext>`. - -If you are familiar with Python packaging and interested in learning how to -turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to -write reusable apps</intro/reusable-apps>`. +When you're comfortable with the admin, read :doc:`part 8 of this +tutorial </intro/tutorial08>` to learn how to use third-party packages. diff --git a/docs/intro/tutorial08.txt b/docs/intro/tutorial08.txt new file mode 100644 index 0000000000..e33a02ec2c --- /dev/null +++ b/docs/intro/tutorial08.txt @@ -0,0 +1,101 @@ +===================================== +Writing your first Django app, part 8 +===================================== + +This tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>` left off. We've +built our web-poll application and will now look at third-party packages. One of +Django's strengths is the rich ecosystem of third-party packages. They're +community developed packages that can be used to quickly improve the feature set +of an application. + +This tutorial will show how to add `Django Debug Toolbar +<https://django-debug-toolbar.readthedocs.io>`_, a commonly used third-party +package. The Django Debug Toolbar has ranked in the top three most used +third-party packages in the Django Developers Survey in recent years. + +.. admonition:: Where to get help: + + If you're having trouble going through this tutorial, please head over to + the :doc:`Getting Help</faq/help>` section of the FAQ. + +Installing Django Debug Toolbar +=============================== + +Django Debug Toolbar is a useful tool for debugging Django web applications. +It's a third-party package maintained by the `Jazzband +<https://jazzband.co>`_ organization. The toolbar helps you understand how your +application functions and to identify problems. It does so by providing panels +that provide debug information about the current request and response. + +To install a third-party application like the toolbar, you need to install +the package by running the below command within an activated virtual +environment. This is similar to our earlier step to :ref:`install Django +<installing-official-release>`. + +.. console:: + + $ python -m pip install django-debug-toolbar + +Third-party packages that integrate with Django need some post-installation +setup to integrate them with your project. Often you will need to add the +package's Django app to your :setting:`INSTALLED_APPS` setting. Some packages +need other changes, like additions to your URLconf (``urls.py``). + +Django Debug Toolbar requires several setup steps. Follow them in `its +installation guide +<https://django-debug-toolbar.readthedocs.io/en/latest/installation.html>`_. +The steps are not duplicated in this tutorial, because as a third-party +package, it may change separately to Django's schedule. + +Once installed, you should be able to see the DjDT "handle" on the right side +of the browser window when you refresh the polls application. Click it to open +the debug toolbar and use the tools in each panel. See the `panels +documentation page +<https://django-debug-toolbar.readthedocs.io/en/latest/panels.html>`__ for more +information on what the panels show. + +Getting help from others +======================== + +At some point you will run into a problem, for example the +toolbar may not render. When this happens and you're unable to +resolve the issue yourself, there are options available to you. + +#. If the problem is with a specific package, check if there's a + troubleshooting of FAQ in the package's documentation. For example the + Django Debug Toolbar has a `Tips section + <https://django-debug-toolbar.readthedocs.io/en/latest/tips.html>`_ that + outlines troubleshooting options. +#. Search for similar issues on the package's issue tracker. Django Debug + Toolbar’s is `on GitHub <https://github.com/jazzband/django-debug-toolbar/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc>`_. +#. Consult the `Django Forum <https://forum.djangoproject.com/>`_. +#. Join the `Django Discord server <https://discord.gg/xcRH6mN4fa>`_. +#. Join the #Django IRC channel on `Libera.chat <https://libera.chat/>`_. + +Installing other third-party packages +===================================== + +There are many more third-party packages, which you can find using the +fantastic Django resource, `Django Packages <https://djangopackages.org/>`_. + +It can be difficult to know what third-party packages you should use. This +depends on your needs and goals. Sometimes it's fine to use a package that's +in its alpha state. Other times, you need to know it's production ready. +`Adam Johnson has a blog post +<https://adamj.eu/tech/2021/11/04/the-well-maintained-test/>`_ that outlines +a set of characteristics a that qualifies a package as "well maintained". +Django Packages shows data for some of these characteristics, such as when the +package was last updated. + +As Adam points out in his post, when the answer to one of the questions is +"no", that's an opportunity to contribute. + +What's next? +============ + +The beginner tutorial ends here. In the meantime, you might want to check out +some pointers on :doc:`where to go from here </intro/whatsnext>`. + +If you are familiar with Python packaging and interested in learning how to +turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to +write reusable apps</intro/reusable-apps>`. diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index c8884c5be9..4ed4f49cf2 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -235,6 +235,7 @@ iterable iterables iteratively ize +Jazzband Jinja jQuery Jupyter |
