Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#29864 closed Cleanup/optimization (fixed)

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

Reported by: Thomas Güttler Owned by: Prabakaran Kumaresshan
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes UI/UX: no

Description (last modified by Tim Graham)

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.

Change History (17)

comment:1 by Tim Graham, 6 years ago

Easy pickings: set
Summary: Hyperlnks from general cache framework docs page to low level APIAdd links from the cache framework topic guide to the low level API
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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

comment:2 by Rand01ph, 6 years ago

Owner: changed from nobody to Rand01ph
Status: newassigned

comment:3 by Rand01ph, 6 years ago

Owner: Rand01ph removed
Status: assignednew

comment:4 by Berry van Mondfrans, 6 years ago

Owner: set to Berry van Mondfrans
Status: newassigned

comment:5 by Berry van Mondfrans, 6 years ago

Owner: Berry van Mondfrans removed
Status: assignednew

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

comment:6 by Tim Graham, 6 years ago

Description: modified (diff)

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

comment:7 by Prabakaran Kumaresshan, 6 years ago

Owner: set to Prabakaran Kumaresshan
Status: newassigned

comment:8 by Prabakaran Kumaresshan, 6 years ago

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 ?

comment:9 by Tim Graham, 6 years ago

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

  • docs/topics/cache.txt

    diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
    index 2ffad67686..bf6cfc2ddf 100644
    a b Accessing the cache  
    788788Basic usage
    789789-----------
    790790
    791 The basic interface is ``set(key, value, timeout)`` and ``get(key)``::
     791.. currentmodule:: django.core.caches
     792
     793The basic interface is:
     794
     795.. method:: cache.set(key, value, timeout)
    792796
    793797    >>> cache.set('my_key', 'hello, world!', 30)
     798
     799.. method:: cache.get(key)
     800
    794801    >>> cache.get('my_key')
    795802    '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.

comment:10 by Prabakaran Kumaresshan, 6 years ago

That might clarify, lets hear from the reporter.

comment:11 by Thomas Güttler, 6 years ago

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.

comment:12 by Prabakaran Kumaresshan, 6 years ago

Has patch: set
Version: 2.1master

comment:13 by Tim Graham, 6 years ago

Patch needs improvement: set

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.

in reply to:  13 comment:14 by Prabakaran Kumaresshan, 6 years ago

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

comment:15 by Prabakaran Kumaresshan, 6 years ago

I have updated the PR with method references

comment:16 by Tim Graham <timograham@…>, 6 years ago

Resolution: fixed
Status: assignedclosed

In 8250538b:

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

comment:17 by Tim Graham <timograham@…>, 6 years ago

In 24a85f4:

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

Backport of 8250538bfc9792c87cd42c27fa778f12e14350cb from master.

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