diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index 19d9063edd..f40daf4dfb 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -121,16 +121,17 @@ Python *packaging* refers to preparing your app in a specific format that can be easily installed and used. Django itself is packaged very much like this. For a small app like polls, this process isn't too difficult. -#. First, create a parent directory for ``polls``, outside of your Django +#. First, create a parent directory for the package, outside of your Django project. Call this directory ``django-polls``. .. admonition:: Choosing a name for your app - When choosing a name for your package, check resources like PyPI to avoid - naming conflicts with existing packages. It's often useful to prepend - ``django-`` to your module name when creating a package to distribute. - This helps others looking for Django apps identify your app as Django - specific. + When choosing a name for your package, check PyPI to avoid naming + conflicts with existing packages. We recommend using a ``django-`` + prefix for package names, to identify your package as specific to + Django, and a corresponding ``django_`` prefix for your module name. For + example, the ``django-ratelimit`` package contains the + ``django_ratelimit`` module. Application labels (that is, the final part of the dotted path to application packages) *must* be unique in :setting:`INSTALLED_APPS`. @@ -138,19 +139,35 @@ this. For a small app like polls, this process isn't too difficult. `, for example ``auth``, ``admin``, or ``messages``. -#. Move the ``polls`` directory into the ``django-polls`` directory. +#. Move the ``polls`` directory into ``django-polls`` directory, and rename it + to ``django_polls``. + +#. Edit ``django_polls/apps.py`` so that :attr:`~.AppConfig.name` refers to the + new module name and add :attr:`~.AppConfig.label` to give a short name for + the app: + + .. code-block:: python + :caption: ``django-polls/django_polls/apps.py`` + + from django.apps import AppConfig + + + class PollsConfig(AppConfig): + default_auto_field = "django.db.models.BigAutoField" + name = "django_polls" + label = "polls" #. Create a file ``django-polls/README.rst`` with the following contents: .. code-block:: rst :caption: ``django-polls/README.rst`` - ===== - Polls - ===== + ============ + django-polls + ============ - Polls is a Django app to conduct web-based polls. For each question, - visitors can choose between a fixed number of answers. + django-polls is a Django app to conduct web-based polls. For each + question, visitors can choose between a fixed number of answers. Detailed documentation is in the "docs" directory. @@ -161,19 +178,18 @@ this. For a small app like polls, this process isn't too difficult. INSTALLED_APPS = [ ..., - "polls", + "django_polls", ] 2. Include the polls URLconf in your project urls.py like this:: - path("polls/", include("polls.urls")), + path("polls/", include("django_polls.urls")), - 3. Run ``python manage.py migrate`` to create the polls models. + 3. Run ``python manage.py migrate`` to create the models. - 4. Start the development server and visit http://127.0.0.1:8000/admin/ - to create a poll (you'll need the Admin app enabled). + 4. Start the development server and visit the admin to create a poll. - 5. Visit http://127.0.0.1:8000/polls/ to participate in the poll. + 5. Visit the ``/polls/`` URL to participate in the poll. #. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the scope of this tutorial, but suffice it to say that code released publicly @@ -251,8 +267,8 @@ this. For a small app like polls, this process isn't too difficult. include LICENSE include README.rst - recursive-include polls/static * - recursive-include polls/templates * + recursive-include django_polls/static * + recursive-include django_polls/templates * #. It's optional, but recommended, to include detailed documentation with your app. Create an empty directory ``django-polls/docs`` for future @@ -266,8 +282,8 @@ this. For a small app like polls, this process isn't too difficult. you add some files to it. Many Django apps also provide their documentation online through sites like `readthedocs.org `_. -#. Try building your package with ``python setup.py sdist`` (run from inside - ``django-polls``). This creates a directory called ``dist`` and builds your +#. Try building your package by running ``python setup.py sdist`` inside + ``django-polls``. This creates a directory called ``dist`` and builds your new package, ``django-polls-0.1.tar.gz``. For more information on packaging, see Python's `Tutorial on Packaging and @@ -299,14 +315,21 @@ working. We'll now fix this by installing our new ``django-polls`` package. python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz -#. With luck, your Django project should now work correctly again. Run the - server again to confirm this. +#. Update ``mysite/settings.py`` to point to the new module name:: -#. To uninstall the package, use pip: + INSTALLED_APPS = [ + "django_polls.apps.PollsConfig", + ..., + ] - .. code-block:: shell +#. Update ``mysite/urls.py`` to point to the new module name:: - python -m pip uninstall django-polls + urlpatterns = [ + path("polls/", include("django_polls.urls")), + ..., + ] + +#. Run the development server to confirm the project continues to work. Publishing your app =================== @@ -326,7 +349,7 @@ the world! If this wasn't just an example, you could now: Installing Python packages with a virtual environment ===================================================== -Earlier, we installed the polls app as a user library. This has some +Earlier, we installed ``django-polls`` as a user library. This has some disadvantages: * Modifying the user libraries can affect other Python software on your system.