Summary

Add thorough documentation for the djblets_utils template tags.

Review Request #7738 — Created Oct. 25, 2015 and submitted Oct. 26, 2015, 12:20 a.m.

Information

Owner

chipx86

Repository

Djblets

Branch

release-0.9.x

Bugs

Depends On

Reviewers

Groups

djblets

People

Description

djblets_utils is one of the oldest modules in Djblets, and its
documentation was really lacking. This change fleshes it out, bringing
it up to current standards, and adds examples showing how to use all the
tags.

This started off as some cleanups to appease Sphinx, but ended up
becoming a complete rewrite of the docs.

Testing Done

Built the docs and read through them.

Issues

Description	From	Last Updated
In the other docstrings, you use "Example:" instead of "Examples:".	AD adriano	Oct. 25, 2015, 10:52 p.m.
Typo: "value" should be "key".	AD adriano	Oct. 25, 2015, 10:56 p.m.
undefined name 'value'	reviewbot	Oct. 25, 2015, 10:52 p.m.
"Turns" is the wrong tense (use something like "Turn"?).	AD adriano	Oct. 25, 2015, 10:56 p.m.

Tool: Pyflakes
Processed Files:
    djblets/util/templatetags/djblets_utils.py



Tool: PEP8 Style Checker
Processed Files:
    djblets/util/templatetags/djblets_utils.py

djblets/util/templatetags/djblets_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
 undefined name 'value'
```

djblets/util/templatetags/djblets_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
In the other docstrings, you use "Example:" instead of "Examples:".
```
1. chipx86 Oct. 25, 2015, 10:48 p.m.
  Good catch.
2. chipx86 Oct. 25, 2015, 10:53 p.m.
  For the record, both work, but it's good to be consistent :)
djblets/util/templatetags/djblets_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Typo: "value" should be "key".
```

djblets/util/templatetags/djblets_utils.py (Diff revision 1)

Should this be "(int, optional)"?

chipx86 Oct. 25, 2015, 10:48 p.m.

Sure. There's no real standard for any of this yet, which is kinda annoying :(

djblets/util/templatetags/djblets_utils.py (Diff revision 1)
The issue has been resolved. Show all issues
```
"Turns" is the wrong tense (use something like "Turn"?).
```
djblets/util/templatetags/djblets_utils.py (Diff revision 1)
```
Another opportunity for "(unicode, optional)"?
```

Change Summary:

Fixed typos and improved docs.

Diff:

Revision 2 (+435 -82)

Show changes

djblets/util/templatetags/djblets_utils.py

Tool: Pyflakes
Processed Files:
    djblets/util/templatetags/djblets_utils.py



Tool: PEP8 Style Checker
Processed Files:
    djblets/util/templatetags/djblets_utils.py

Ship it!

Ship It!

AD

adriano Oct. 25, 2015, 11:07 p.m.
```
Heheh. Always wanted to do this. =]
```

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to release-0.9.x (12a7c27)