Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#31126 closed Cleanup/optimization (fixed)

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

Reported by: Abhijeet Viswa Owned by: Abhijeet Viswa
Component: Documentation Version: dev
Severity: Normal Keywords: documentation, static-files
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description (last modified by 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.

Change History (6)

comment:1 by Mariusz Felisiak, 5 years ago

Summary: Document static file namespaces (prefixes) in Managing Static Files documentationAdd a cross-reference to the staticfiles prefixes in the "Configuring static files" docs.
Triage Stage: UnreviewedAccepted

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)
 ~~~~~~~~~~~~~~~~~~~

in reply to:  1 comment:2 by Abhijeet Viswa, 5 years ago

Description: modified (diff)

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.

comment:3 by Abhijeet Viswa, 5 years ago

Description: modified (diff)

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

comment:4 by Abhijeet Viswa, 5 years ago

Has patch: set

comment:5 by GitHub <noreply@…>, 5 years ago

Resolution: fixed
Status: assignedclosed

In a45c8d7a:

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

comment:6 by Carlton Gibson <carlton.gibson@…>, 5 years ago

In 7d48a4b7:

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

Backport of a45c8d7ad04b73e33b6989c3ffa2b8c51ae3e83b from master

Note: See TracTickets for help on using tickets.
Back to Top