Summary

Add documentation for the Extension and JSExtension classes.

Review Request #8513 — Created Oct. 31, 2016 and submitted Nov. 17, 2016, 2:27 p.m.

Information

Owner

chipx86

Repository

Djblets

Branch

release-0.9.x

Bugs

Depends On

Commit

04dfbe8...

Reviewers

Groups

djblets

People

Description

These classes are pretty important, but we didn't have any real class
reference documentation for the attributes. This change introduces
documentation for these, fleshes out some of the docs for methods, and
updates one of the attributes to be a documentable @cached_property
(using Djblets's new, smarter version).

Something worth noting is that Sphinx does not provide documentation
inheritance for attribute docs, so the Review Board documentation still
won't have those documented, but at least we have a good reference now
in Djblets.

Testing Done

Built the docs and looked through them. Everything was documented.

Issues

Description	From	Last Updated
Col: 80 E501 line too long (80 > 79 characters)	reviewbot	Nov. 15, 2016, 5:45 p.m.
This should point out that this needs to be JSON-serializable.	david	Nov. 15, 2016, 5:46 p.m.
set of what?	david	Nov. 15, 2016, 5:47 p.m.
"parent package" is funky nomenclature. How about "the extension's python package metadata". This should probably also explain why you might …	david	Nov. 15, 2016, 5:48 p.m.
It's kind of bizarre to suggest using a raw string here.	david	Nov. 15, 2016, 5:49 p.m.
This isn't a list.	david	Nov. 15, 2016, 5:49 p.m.
This isn't a list.	david	Nov. 15, 2016, 5:49 p.m.

Tool: Pyflakes
Processed Files:
    djblets/extensions/extension.py



Tool: PEP8 Style Checker
Processed Files:
    djblets/extensions/extension.py

djblets/extensions/extension.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Col: 80
 E501 line too long (80 > 79 characters)
```

djblets/extensions/extension.py (Diff revision 1)
The issue has been resolved. Show all issues
```
This should point out that this needs to be JSON-serializable.
```
djblets/extensions/extension.py (Diff revision 1)
The issue has been resolved. Show all issues
```
set of what?
```

djblets/extensions/extension.py (Diff revision 1)

The issue has been resolved. Show all issues

"parent package" is funky nomenclature. How about "the extension's python package metadata".
This should probably also explain why you might want to do this, such as having a displayed name with a space in it.

djblets/extensions/extension.py (Diff revision 1)
The issue has been resolved. Show all issues
```
It's kind of bizarre to suggest using a raw string here.
```
djblets/extensions/extension.py (Diff revision 1)
The issue has been resolved. Show all issues
```
This isn't a list.
```
djblets/extensions/extension.py (Diff revision 1)
The issue has been resolved. Show all issues
```
This isn't a list.
```

Change Summary:


Fixed some wording to be more clear to a few different docstrings.
Fixed information on some types.
Added examples of when you'd define custom package metadata.
Changed a regex in docs to use Sphinx's :regexp:.

Commit:

c8a4c6c7f8385a3ad37724e858ccc188994cd535

04dfbe808ef12bda0bc5f18ea130180e2b594a6b

Diff:

Revision 2 (+189 -22)

Show changes

djblets/extensions/extension.py

Tool: Pyflakes
Processed Files:
    djblets/extensions/extension.py



Tool: PEP8 Style Checker
Processed Files:
    djblets/extensions/extension.py

Ship it!

```
Ship It!
```

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