Documentation for new example service should be more comprehensive
| Affects | Status | Importance | Assigned to | Milestone | |
|---|---|---|---|---|---|
| lazr.restful |
Triaged
|
Low
|
Unassigned | ||
Bug Description
lp:~leonardr/lazr.restful/wsgi.example is about to be merged with trunk, which will add a great new example web service and some nice docs.
I'd like to see src/lazr/
- Is the configuration object registered somehow?
- Where do I learn about how to write a configuration object?
- In the implementation, you seem to stub out some of the values. Maybe
describing specifically what you are doing here would be a good idea.
- You mentioned named operations. What are they, why do I care, and where do
I learn more?
- This has been a great example of a read-only service. What about writable
services? Where do I read more?
- Where do I find more about annotating my interface?
- Somewhere it would be worthwhile to describe the problem of circular
references and strategies to combat it, and possible ways to address it in
the future (e.g., maybe a deferred object that takes a string and imports
what it points to when something tries to use it)
- you don't mention site.zcml. It's worth mentioning and explaining, since you
explicitly load it and it has important inclusions, and it includes
configure.zcml. Alternatively, you could just combine the two zcml files
so that a user only has to look at one file (but then they maybe don't
clearly see what is general set up? maybe comments in the zcml are
appropriate for this as well?).
| Stephen Waterbury (waterbug) wrote | #1 |
| Changed in lazr.restful: | |
| status: | New → Triaged |
| importance: | Undecided → Low |
In following the instructions in README.txt for running the example service, I first set up a virtualenv and then installed lazr.restful there. There is no bootstrap.py in the lazr.restful distribution, so I downloaded one and ran it, but this had no apparent effect. At any rate, no bin/run was created by anything. Barry Warsaw suggested to just use bin/python instead of bin/run, and that worked. So my procedure was:
mkdir lazrenv
cd lazrenv
virtualenv --no-site-packages .
./bin/easy_install lazr.restful
./bin/python [path to lazr.restful source]
Since the current README.txt instructions don't work and this does, I suggest it as a patch (see attached) -- the patch also contains another minor correction to the README.txt.