Add a cross-reference to the staticfiles prefixes in the "Configuring static files" docs.

[Abhijeet Viswa]

Currently, the Managing Static Files documentation page doesn't mention anything about namespaces (prefixes). It is logical to expect information regarding this on the page that deals with static files. However, the details are mentioned in Django Settings page under the setting.

I propose that the documentation be moved from Settings page to Managing Static Files page and add a link from the former to the latter. A quicker alternative would be the other way round.

[Mariusz Felisiak]

IMO both docs are in the right places, moreover howto/static-files/index.txt mentions namespaces in the Static file namespacing admonition. Nevertheless adding a cross reference to the docs/ref/settings.txt seems like a good idea, e.g.

--- a/docs/howto/static-files/index.txt
+++ b/docs/howto/static-files/index.txt
     distinguish between them. We need to be able to point Django at the right
-    one, and the best way to ensure this is by *namespacing* them. That is,
-    by putting those static files inside *another* directory named for the
-    application itself.
+    one, and the best way to ensure this is by :ref:`namespacing them
+    <staticfiles-dirs-prefixes>`. That is, by putting those static files inside
+    *another* directory named for the application itself.

--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
 
+.. _staticfiles-dirs-prefixes:
+
 Prefixes (optional)
 ~~~~~~~~~~~~~~~~~~~

[Abhijeet Viswa]

Replying to felixxm:

IMO both docs are in the right places, moreover howto/static-files/index.txt mentions namespaces in the Static file namespacing admonition. Nevertheless adding a cross reference to the docs/ref/settings.txt seems like a good idea, e.g.

--- a/docs/howto/static-files/index.txt
+++ b/docs/howto/static-files/index.txt
     distinguish between them. We need to be able to point Django at the right
-    one, and the best way to ensure this is by *namespacing* them. That is,
-    by putting those static files inside *another* directory named for the
-    application itself.
+    one, and the best way to ensure this is by :ref:`namespacing them
+    <staticfiles-dirs-prefixes>`. That is, by putting those static files inside
+    *another* directory named for the application itself.

--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
 
+.. _staticfiles-dirs-prefixes:
+
 Prefixes (optional)
 ~~~~~~~~~~~~~~~~~~~

The Static file namespacing admonition in howto/static-files/index.txt mentions namespaces in relation with static files for a particular app (my_app/static). I am talking about prefixes in context of FileSystemFinder and the STATICFILE_DIRS setting.

The reason why I speak of prefixes in particular is because I had a particular case where I needed them to be served as static files and at the same time include them in a meaningful directory structure of my code repository. The default action is the contents of the files are moved to the STATIC_ROOT folder. Using prefixes meant I could namespace the static files properly and hence link to them (from outside templates) using straight forward and intutive links.

I'll have a patch ready by tonight.

[Abhijeet Viswa]

I removed the description in my previous comment by mistake. Sorry for that.
Adding it back in here.

[Abhijeet Viswa]

Patch: ​https://github.com/django/django/pull/12261

[GitHub <noreply@…>]

In a45c8d7a:

Fixed #31126 -- Doc'd STATICFILES_DIRS namespacing in static files how-to.

[Carlton Gibson <carlton.gibson@…>]

In 7d48a4b7:

[3.0.x] Fixed #31126 -- Doc'd STATICFILES_DIRS namespacing in static files how-to.

Backport of a45c8d7ad04b73e33b6989c3ffa2b8c51ae3e83b from master