Add links from the cache framework topic guide to the low level API

[Thomas Güttler]

Please make at least the first cache.get() and cache.set() occurrences a hyperlink to the low-level API docs.

​https://docs.djangoproject.com/en/dev/topics/cache/

My use question on mind: Is there a way to get a default-value from the cache like the get() method can be used to return a default-value from a dict.

[Tim Graham]

That looks fine. We don't want to add redundant links everywhere because each change requires translators to redo work.

[Berry van Mondfrans]

No other methods have any links, so why should they be added for these two?

[Tim Graham]

It would be nice to link the first instance of all methods.

[Prabakaran Kumaresshan]

I'm just wondering where does the low level document for get and set methods are available, there isn't any document on cache other than the topic on cache. Or is it the documentation of respective backends ?

[Tim Graham]

I'm not sure. I guess I accepted the ticket prematurely. We could possibly do something like this:

docs/topics/cache.txt

@@ -788 +788 @@
 Basic usage
 -----------
 
-The basic interface is ``set(key, value, timeout)`` and ``get(key)``::
+.. currentmodule:: django.core.caches
+
+The basic interface is:
+
+.. method:: cache.set(key, value, timeout)
 
     >>> cache.set('my_key', 'hello, world!', 30)
+
+.. method:: cache.get(key)
+
     >>> cache.get('my_key')
     'hello, world!'

or create a separate reference document if it's useful. Maybe the ticket reporter can elaborate as "the first cache.get() and cache.set() occurrences" seem to be in the "low-level cache API" section.

[Prabakaran Kumaresshan]

That might clarify, lets hear from the reporter.

[Thomas Güttler]

I think there are two issues, if you look at in detail.

First: It would be really useful if there is a URL for every public method of django. In this case cache.get() and cache.set(). This makes it much easier
if you write answers or questions at (for example) stackoverflow. You can write then: "you should use method cache.get()" and make "cache.get()" a hyperlink to the docs.
Tim Graham already created a solution for this (see above). Thank you Tim.

Second: Hyperlinks inside the docs are useful. They do not need to everywhere. I think it is a pragmatic solution if the first usage of a method name in a chapter is a hyperlink.

[Prabakaran Kumaresshan]

​PR

[Tim Graham]

My patch which was submitted verbatim in the PR isn't complete. There are many more cache methods that should be documented in a similar fashion.

[Prabakaran Kumaresshan]

Replying to Tim Graham:

My patch which was submitted verbatim in the PR isn't complete. There are many more cache methods that should be documented in a similar fashion.

Ok sure let me check

[Prabakaran Kumaresshan]

I have updated the ​PR with method references

[Tim Graham <timograham@…>]

In 8250538b:

Fixed #29864 -- Added link targets for low-level cache API.

[Tim Graham <timograham@…>]

In 24a85f4:

[2.1.x] Fixed #29864 -- Added link targets for low-level cache API.

Backport of 8250538bfc9792c87cd42c27fa778f12e14350cb from master.