[Django] #29864: Hyperlnks from general cache framework docs page to low level API
Django
------------------------------------------+------------------------
Reporter: Thomas Güttler | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 2.1
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------+------------------------
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/2.1/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.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
--------------------------------------+------------------------------------
Reporter: Thomas Güttler | Owner: nobody
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by Tim Graham):
* type: Uncategorized => Cleanup/optimization
* easy: 0 => 1
* stage: Unreviewed => Accepted
Comment:
That looks fine. We don't want to add redundant links everywhere because
each change requires translators to redo work.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:1>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
* owner: nobody => Rand01ph
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:2>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by Rand01ph):
* owner: Rand01ph => (none)
* status: assigned => new
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:3>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
* status: new => assigned
* owner: (none) => Gastror
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:4>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by Gastror):
* owner: Gastror => (none)
* status: assigned => new
Comment:
No other methods have any links, so why should they be added for these
two?
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:5>
Django
--------------------------------------+------------------------------------
Reporter: Thomas Güttler | Owner: (none)
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Old description:
> 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/2.1/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.
New description:
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.
--
Comment (by Tim Graham):
It would be nice to link the first instance of all methods.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:6>
Django
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 2.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by Prabakaran Kumaresshan):
* owner: (none) => Prabakaran Kumaresshan
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by 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 ?
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham):
I'm not sure. I guess I accepted the ticket prematurely. We could possibly
do something like this:
{{{ #!diff
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 2ffad67686..bf6cfc2ddf 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -788,9 +788,16 @@ Accessing the cache
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by Prabakaran Kumaresshan):
That might clarify, lets hear from the reporter.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by Prabakaran Kumaresshan):
* has_patch: 0 => 1
* version: 2.1 => master
Comment:
[https://github.com/django/django/pull/10567 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 0 => 1
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Prabakaran Kumaresshan):
Replying to [comment:13 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
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Prabakaran Kumaresshan):
I have updated the [https://github.com/django/django/pull/10567 PR] with
method references
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"8250538bfc9792c87cd42c27fa778f12e14350cb" 8250538b]:
{{{
#!CommitTicketReference repository=""
revision="8250538bfc9792c87cd42c27fa778f12e14350cb"
Fixed #29864 -- Added link targets for low-level cache API.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:16>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner:
Type: | Prabakaran Kumaresshan
Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"24a85f44c2726bbb6557731af70f6c52302ddac3" 24a85f4]:
{{{
#!CommitTicketReference repository=""
revision="24a85f44c2726bbb6557731af70f6c52302ddac3"
[2.1.x] Fixed #29864 -- Added link targets for low-level cache API.
Backport of 8250538bfc9792c87cd42c27fa778f12e14350cb from master.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/29864#comment:17>