Paul McNett wrote: > Carl Karsten wrote: >> Paul McNett wrote: >>> Carl Karsten wrote: >>>>> -> /home/pmcnett/dabo >>>>> top level dabo directory, the one with AUTHORS and README and (most >>>>> importantly) the one with the dabo subdirectory (the top-level of the >>>>> importable dabo stuff). >>>> So you have /home/pmcnett/dabo/dabo right? >>> Yes. What was the problem again? >> "dabo dir" is not definitive - it does not identify a dir. makes for crappy >> docs. > > I understand, but don't have any answers, as you've probably guessed.
That's cuz you gave them both to me yesterday. I'll give them back when I am done. > What is missing from the picture is a graphical installer, that guides > the user through the process of getting dabo "installed", which is > basically: > > 1) download > 2) put in a smart location based on whether only this user needs access > to it (home dir) or all users need access to it (/usr/local/lib; > c:\Program Files). > 3) add the dabo.pth to python's site-packages > > Someone should write one in Dabo :) >>>> That bothers me. so does dabo/dabo/dabo, which is what I had for a while, >>>> then >>>> I switched to dabo/trunk/dabo/dabo, which I don't like either. >>> I actually have: >>> >>> ~/dabo-full/ >>> ~/dabo-full/branches >>> ~/dabo-full/tags >>> ~/dabo-full/trunk >>> >>> and a symlink: >>> ln -s ~/dabo-full/trunk dabo >>> >> Is that your final answer? > > The outer dabo directory contains stuff that isn't needed for actually > using dabo. Mostly, it is where the setup.py lives. When you run 'python > setup.py install', you end up with the inner dabo directory underneath > your python's site-packages. > > This works great, and when you want to update you just download again > and re-run 'python setup.py install' and everything is hunky-dory. > > But for developers, that dance gets inconvenient, as we want to update > at just about every single revision, and sometimes the needs are more > complex because we also want to do things like swap in Carl's branch, or > test-run an actual tagged release. So, developers really should come up > with their own source code management that works for them. > > In addition, sometimes when working with users we say "please update > from the latest subversion" Only sometimes? :) (see way below before replying to this) > which can be pretty cryptic, I imagine, from > their point of view, but that statement assumes that they are set up > with developer-style source code management, and developers in the heat > of the moment forget that this isn't the case. > > So, I agree that we need some docs. It is just that the dabo/dabo thing > doesn't seem to me to be the best place to focus. The outer dabo is > where the setup.py lives; the inner dabo is the dabo library. I hate to ask... but what is projects/dabo/lib ? I would be happy to use the term 'library' if it weren't for that lib dir. > >>> Why are you bothered? The outer Dabo can be named whatever you want, so >>> change it! >> That's what I am trying to do, but can't figure out what to change it to. >> >>> cd ~ >>> svn co http://svn.dabodev.com/trunk Dabo-Outer >>> >> I'm not going to change it to Dabo-Outer. :) >> >>> It is the interior 'dabo' that is important, because it is the package name. >> All the dirs are somewhat important. if they aren't, then delete them :) >> >> btw - the package name does not have to be the same as the dir name. but >> making >> it different would make things more confusing, which is not what I am trying >> to do. > > Ok, you got me. How do you make a python package that isn't named by its > directory name? Turned around, how would python find the package in > 'import dabo' if the directory were named 'inner-dabo' instead? [EMAIL PROTECTED]:~$ sudo ln -s /home/carl/src/projects/inner-dabo/ /usr/lib/python2.4/site-packages/dabo For windows you have to patch python2.4\site.py so that it conforms to the way I interpreted its docstring :) I was expecting to be able to put "/home/carl/src/projects/inner-dabo" in dabo.pth, but it seems the name of the .pth file isn't used. (you can call the file foo.pth, and as long as the last dir is dabo.) I went looking for details, found "whose name has the form package.pth" http://www.python.org/doc/lib/module-site.html - but as far as I can tell, that is incorrect. As I was trying to see exactly what the code did (this is so cool - always wanted to be able to do this when testing VFP) I found a 2nd doc bug: site.py addpackage: "Add a new path to known_paths by combining sitedir and 'name' or execute sitedir if it starts with 'import'""" my suggestion: """Add a new path to known_paths by combining sitedir and 'name' or execute lines in name.pth that start with 'import'""" Did you know it it would execute import statements? > > >>>> -> /home/pmcnett/dabo >>>> -> /home/pmcnett/daboide >>>> -> /home/pmcnett/ss >>>> >>>> I think you are going to find your home to become cluttered. Even if >>>> works for >>>> you, I don't feel good recommending it. >>> Um, yeah, my home directory is always cluttered. But every now and then >>> I clean house. And I have yet to encounter an actual problem with a >>> cluttered home directory. I never have trouble finding anything, which >>> would seem to be the main thing to be concerned about. >> "be sure to clean house now and then." not sure that should be the official >> policy :) > > I was trying to show how simple this can be, that overthinking things up > front can cause lots of unjustified wheel-spinning. Why *not* tell > people to put it in their home directory? Because some (most is my guess) wont - they will make a dir called dabo, and dump all 3 sets of code in it, and then start asking for help. > We aren't in charge of how people organize their filesystems, and it > isn't up to us to dictate it. Apparently I didn't make myself clear: the docs will not dictate, just suggest. I want the suggestion to be something A) well defined, B) reasonable and C) easy to communicate about later. "something sensible" fails A, dir1 fails B, dabo/dabo/dabo fails C. ~ fails all 3. > >>>>> somewhere and importable from Python. It matters not where individuals >>>>> choose to place their directories, >>>> true, the docs should make that clear. >>>> >>>>> and I'd argue that part of the >>>>> process of initiation into something like Dabo would be for people to >>>>> come up with their own best practices themselves. It isn't rocket science. >>>>> >>>> So we should just replace the docs with "you figure it out." ? :) > > Actually... ;) While I wish that computer users today were comfortable > with concepts like files and directories, especially since such concepts > would seem to be building blocks for understanding things like python > packages and working with dabo, I understand that some amount of > guidance is going to be necessary. And if you can create a simple doc > that we can point to instead of having to spin cycles giving the answer > over and over again, I'm all for it! Exactly what I am trying to do. The problem I have right out the gate is the current naming scheme is hard to document. Given that "it isn't rocket science" (which I agree with) i think the 'hard to doc' is an indication of a deeper problem: poor choice of names. so I am trying to fix the root, which will have a side effect of making the docs easier to write and easier to understand. > > >>> This is what the docs should say: >>> >>> 1) download dabo (use tarball, svn, whatever) >>> 2) wherever you put it, your choice but write it down, because you need >>> it in step 3. >> "write it down"! amusing, but no, the docs should not say that. or >> anything >> like that. Not if they don't have to, and they don't. It does get around >> the >> funky dir name issue, but I am pretty sure coming up with better dir names >> is a >> better solution. > > Again with the funky dir name. You are referring to dabo/dabo? dabo/dabo and dabo/dabo/dabo (which I found in the wild - not just my system) > > >>> 3) put a dabo.pth file in your python site-packages directory[1] >>> pointing to the location of your outer dabo directory. So, if you >>> downloaded to ~/, this would be ~/dabo. >> wouldn't it be ~/dabo/dabo ? > > No, it would be ~/dabo. This tells python to look for packages in > ~/dabo, and that is where the dabo package (the inner dabo) resides. Note that you had to attempt to clarify what you said. if the dirs had reasonable names, your statement would be both shorter and clearer. > Note that the ~/ shorthand *should not* be specified in the dabo.pth > file, because that will resolve to different locations depending on > logged-on user. Maybe the admin wants that :) (like this thread needs more tangents. > >>> [1] Windows: c:\python2x\lib\site-packages; Linux: >>> /usr/lib/python2x/site-packages; Mac: >>> /Library/Frameworks/Python.framework/Versions/2.5/lib/python25.zip >> python25.zip ? > > Oops, cut/pasted from the wrong line: > /Library/Frameworks/Python.framework/Versions/2.5/lib/site-packages Kinda figured. There is that Library term again. I think library/dabo/lib is better than dabo/dabo. but not by much. > > >>>> The day that someone installs Dabo is not the day they should be figuring >>>> this >>>> kind of thing out. Good chance they are overwhelmed with things to figure >>>> out, >>>> and having a suggested path to follow really helps. Even for seasoned >>>> python >>>> programmers, the concept of some abstract classes may be new (I bet most >>>> are use >>>> to working with modules) and a seperate dir of tools (like ide) may also >>>> be new. >>>> It certainly isn't the normal set of things you get with anything I have >>>> seen. >>> I agree that there should be a simple set of instructions. >> Then stop with all that "you figure it out" style stuff :) >> >> > The easiest >>> first step is what is described in README: >> geeze - more docs. I think this is the one project I have seen that has too >> much docs. > > Agreed that we have too many places with things that can be considered > "docs". > I would add the various docs I find to the status page if could find the page and my password :) > >>> python setup.py install >>> >>> Which works 90% of the time. So the first thing people get is a good >> >> What are you basing 90% on? not that I am disagreeing, but I bet you have >> no >> idea how many people try it and what the results are. > > No, but it follows what other python projects do, which I believe is the > smart thing to do. Nothing dabo-specific about the install. > All things considered, I have a feeling it is much lower than the norm. but given that I don't think I have ever run il.. > >> If it really is good enough, why are there all the other docs? > > Because to hack on dabo, you likely want a different setup. oh - it does that, which doesn't address what I am trying to address. I am not too worried about the "install and forget it" installs - Those are a sub set of the hacker setup - so it it will just fall into place. >> > install of dabo, and then they can figure out how to get the .pth thing >> > working when they get tired of installing dabo when they merely want an >> > update. >> > >> >> Why won't svn update work? > > It would, but it would be a dance: > > cd /tmp > svn up dabo > python dabo/setup.py install ah - install yanks the code that gets run away from what snv up would update. > > I think we need a black and white "here's how to install" for new users, > which would be about 30 words total. Then we need a "further > installation discussion" for hackers. I am even up for making it one long path: Do this, cuz someday this will be all you have to do. work with it for a few hours and then then undo it like this, cuz today isn't someday. here is how you should do it today. Carl K _______________________________________________ Post Messages to: [email protected] Subscription Maintenance: http://leafe.com/mailman/listinfo/dabo-users Searchable Archives: http://leafe.com/archives/search/dabo-users This message: http://leafe.com/archives/byMID/dabo-users/[EMAIL PROTECTED]
