From 757c456d232279ae57546c9c39a9f81183c8a82f Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Tue, 7 Feb 2023 08:26:37 -0600 Subject: [PATCH] [4.2.x] Fixed #34146 -- Added 3rd-party lib tutorial step. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/index.txt | 3 +- docs/intro/index.txt | 1 + docs/intro/reusable-apps.txt | 2 +- docs/intro/tutorial07.txt | 11 +--- docs/intro/tutorial08.txt | 101 +++++++++++++++++++++++++++++++++++ docs/spelling_wordlist | 1 + 6 files changed, 108 insertions(+), 11 deletions(-) create mode 100644 docs/intro/tutorial08.txt diff --git a/docs/index.txt b/docs/index.txt index bbf237bb598..f4878fc8505 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 ` | :doc:`Part 5: Testing ` | :doc:`Part 6: Static files ` | - :doc:`Part 7: Customizing the admin site ` + :doc:`Part 7: Customizing the admin site ` | + :doc:`Part 8: Adding third-party packages ` * **Advanced Tutorials:** :doc:`How to write reusable apps ` | diff --git a/docs/intro/index.txt b/docs/intro/index.txt index 29462c6f9b3..ca4836367f5 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 f0fa4b13064..c3b951dfdb2 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 ` +This advanced tutorial begins where :doc:`Tutorial 8 ` 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 35205e6119a..54567fcbb54 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 `. - -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`. +When you're comfortable with the admin, read :doc:`part 8 of this +tutorial ` 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 00000000000..e33a02ec2cc --- /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 ` 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 +`_, 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` 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 +`_ 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 +`. + +.. 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 +`_. +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 +`__ 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 + `_ that + outlines troubleshooting options. +#. Search for similar issues on the package's issue tracker. Django Debug + Toolbar’s is `on GitHub `_. +#. Consult the `Django Forum `_. +#. Join the `Django Discord server `_. +#. Join the #Django IRC channel on `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 `_. + +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 +`_ 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 `. + +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`. diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index c8884c5be98..4ed4f49cf2e 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -235,6 +235,7 @@ iterable iterables iteratively ize +Jazzband Jinja jQuery Jupyter