Thanks for your useful remarks! Indeed most of the things you point out can be improved. Some remarks inline.
sensimilla a écrit : > Hi Guys > > I am working through the plugin tutorial, I have some small programming > experience but not in python so I am coming to this as a total noob. I > am using ubuntu 8.10. I do have enough knowledge to work out or around > the problems below but it would be nice if the tutorial 'just worked'. > So I will tell you the problems I had so that the tutorial can be improved. > > The first problem I had was when I tried to run setup.py. Python just > gave an error: > > "SyntaxError: Non-ASCII character '\xc3' in file setup.py on line 11, > but no encoding declared" > I fixed it by adding to the front of the file. > # -*- coding: utf-8 -*- > So maybe that should be included in the given setup.py files. Yes, as discussed in PEP 263 (http://www.python.org/dev/peps/pep-0263/), it is a good practice to explicitely state the encoding of source files. > The next one is that there is confusion about what goes where. The command: > "python elisa-plugins/elisa/plugins/apple-trailers/setup.py egg_info -e > elisa-plugins/" > only works if run from the directory that you originally created the > folder structure in (in my case ~/). If this is intentional then you > need to mention that people need to cd up to that folder before running > the command. I reckon commands should be given relative to the most common working directory, i.e. in this case "~/elisa-plugins/elisa/plugins/apple-trailers/". If a change of working directory is needed then it should always be explicit in the instructions. > Next problem is that when you run: > "bzr add elisa_plugin_apple_trailers.egg-info" > it doesn't work because that folder is in ~/elisa-plugins not in > ~/elisa-plugins/elisa/plugins/apple-trailers/ So where is it supposed to > be? do i need to cd there before running the command? should it actually > be in ~/elisa-plugins/elisa/plugins/apple-trailers/ and the setup.py > command is wrong? >From what I understand this is an inconsistency in the tutorial. Indeed there is no way one can add a file that is outside of the branch's root directory structure. > Further confusion came with the next bit about resources. It says "we > can just put the file in the directory's root". Does this means the png > file *and* the resource.conf ? Which folder is the directorys root? ~/ > or ~/elisa-plugins or ~/elisa-plugins/elisa/plugins/apple-trailers. A > note somewhere near the start about the root directory and general > directory structure might be useful. If the resource is an image logo for the plugin then it should go in an "icons/" subdirectory. Otherwise wherever you want to drop it. As a rule of thumb, if you have lots of (image) resources, try to group them in a "data/" subfolder, or the like. The "resources.conf" file should go at the root of the plugin (i.e. "~/elisa-plugins/elisa/plugins/apple-trailers/") > Well that's as far as I got so far. I also corrected a typo that I > found. I really like Elisa but the documentation is quite poor and there > are very few plugins. I hope I can help to improve both these situations. Again, thanks a lot for your feedback. Indeed there is a lot we can do to improve the existing documentation and write some more, and your help is appreciated. Cheers, Olivier
