mirror of
https://github.com/django/django.git
synced 2025-02-28 19:44:35 +00:00
[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
This commit is contained in:
parent
e8a39da396
commit
757c456d23
@ -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 4: Forms and generic views <intro/tutorial04>` |
|
||||||
:doc:`Part 5: Testing <intro/tutorial05>` |
|
:doc:`Part 5: Testing <intro/tutorial05>` |
|
||||||
:doc:`Part 6: Static files <intro/tutorial06>` |
|
: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:**
|
* **Advanced Tutorials:**
|
||||||
:doc:`How to write reusable apps <intro/reusable-apps>` |
|
:doc:`How to write reusable apps <intro/reusable-apps>` |
|
||||||
|
@ -17,6 +17,7 @@ place: read this material to quickly get up and running.
|
|||||||
tutorial05
|
tutorial05
|
||||||
tutorial06
|
tutorial06
|
||||||
tutorial07
|
tutorial07
|
||||||
|
tutorial08
|
||||||
reusable-apps
|
reusable-apps
|
||||||
whatsnext
|
whatsnext
|
||||||
contributing
|
contributing
|
||||||
|
@ -2,7 +2,7 @@
|
|||||||
Advanced tutorial: How to write reusable apps
|
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
|
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.
|
you can reuse in new projects and share with other people.
|
||||||
|
|
||||||
|
@ -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
|
installed Django app. Instead of using that, you can hard-code links to
|
||||||
object-specific admin pages in whatever way you think is best.
|
object-specific admin pages in whatever way you think is best.
|
||||||
|
|
||||||
What's next?
|
When you're comfortable with the admin, read :doc:`part 8 of this
|
||||||
============
|
tutorial </intro/tutorial08>` to learn how to use third-party packages.
|
||||||
|
|
||||||
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>`.
|
|
||||||
|
101
docs/intro/tutorial08.txt
Normal file
101
docs/intro/tutorial08.txt
Normal file
@ -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>`.
|
@ -235,6 +235,7 @@ iterable
|
|||||||
iterables
|
iterables
|
||||||
iteratively
|
iteratively
|
||||||
ize
|
ize
|
||||||
|
Jazzband
|
||||||
Jinja
|
Jinja
|
||||||
jQuery
|
jQuery
|
||||||
Jupyter
|
Jupyter
|
||||||
|
Loading…
x
Reference in New Issue
Block a user