Thread: [SQLObject] Moving docs around
SQLObject is a Python ORM.
Brought to you by:
ianbicking,
phd
From: Ian B. <ia...@co...> - 2005-11-12 02:26:34
|
I'm thinking that documentation shouldn't be branched like other parts of the code. Instead I'd like to keep just a single branch of documentation, and include notes directly in the code about support. So as we add features in the svn trunk, we'll put them in but just note that they are only available in that version. That'll be useful later to know when features were added, though we'll remove the notes at a certain point. For branches, documentation should go in comments with branches named after the label, like: .. comment: branch-name Text here... This will also mean that at any time we can regenerate and upload a new copy of the documentation. I'll be putting the docs in http://svn.colorstudy.com/SQLObject/docs My only real concern is how this effects patches. But I'll be putting in svn:externals so that the layout won't change too much in a checkout, so we'll see how that works. If you have outstanding changes to the documentation it might be good to get them in; I'm guessing you'll have to blow away some directories to get svn up to work after this move. -- Ian Bicking | ia...@co... | http://blog.ianbicking.org |
From: Kevin D. <da...@gm...> - 2005-11-12 03:23:22
|
I came to roughly the same conclusion for TurboGears. I am generating the site from the trunk, but marking the unreleased portions. Though the site is generated from the trunk, the documentation does still get branched/tagged with the code. So, if you go back to an old version, you can also see the corresponding site from the time. (Whether that's useful or not remains to be seen... I was just pointing out that I've left the code and docs together rather than separating out the docs...) Kevin On 11/11/05, Ian Bicking <ia...@co...> wrote: > I'm thinking that documentation shouldn't be branched like other parts > of the code. Instead I'd like to keep just a single branch of > documentation, and include notes directly in the code about support. So > as we add features in the svn trunk, we'll put them in but just note > that they are only available in that version. That'll be useful later > to know when features were added, though we'll remove the notes at a > certain point. > > For branches, documentation should go in comments with branches named > after the label, like: > > .. comment: branch-name > > Text here... > > This will also mean that at any time we can regenerate and upload a new > copy of the documentation. I'll be putting the docs in > http://svn.colorstudy.com/SQLObject/docs > > My only real concern is how this effects patches. But I'll be putting > in svn:externals so that the layout won't change too much in a checkout, > so we'll see how that works. > > If you have outstanding changes to the documentation it might be good to > get them in; I'm guessing you'll have to blow away some directories to > get svn up to work after this move. > > -- > Ian Bicking | ia...@co... | http://blog.ianbicking.org > > > ------------------------------------------------------- > SF.Net email is sponsored by: > Tame your development challenges with Apache's Geronimo App Server. Downl= oad > it for free - -and be entered to win a 42" plasma tv or your very own > Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php > _______________________________________________ > sqlobject-discuss mailing list > sql...@li... > https://lists.sourceforge.net/lists/listinfo/sqlobject-discuss > -- Kevin Dangoor Author of the Zesty News RSS newsreader email: ki...@bl... company: http://www.BlazingThings.com blog: http://www.BlueSkyOnMars.com |
From: Jorge G. <go...@ie...> - 2005-11-12 03:35:21
|
Kevin Dangoor <da...@gm...> writes: > I came to roughly the same conclusion for TurboGears. I am generating > the site from the trunk, but marking the unreleased portions. Though > the site is generated from the trunk, the documentation does still get > branched/tagged with the code. So, if you go back to an old version, > you can also see the corresponding site from the time. (Whether that's > useful or not remains to be seen... I was just pointing out that I've > left the code and docs together rather than separating out the > docs...) I also believe this is better (keeping docs and code together). From other projects of mine, this was the best way to obtain information about one specific version, otherwise you'd have to keep a map like "revision X of code corresponds to revision Y of documentation minus notes A, B and C"... -- Jorge Godoy <go...@ie...> |
From: Ian B. <ia...@co...> - 2005-11-12 17:48:40
|
Jorge Godoy wrote: > Kevin Dangoor <da...@gm...> writes: > > >>I came to roughly the same conclusion for TurboGears. I am generating >>the site from the trunk, but marking the unreleased portions. Though >>the site is generated from the trunk, the documentation does still get >>branched/tagged with the code. So, if you go back to an old version, >>you can also see the corresponding site from the time. (Whether that's >>useful or not remains to be seen... I was just pointing out that I've >>left the code and docs together rather than separating out the >>docs...) > > > I also believe this is better (keeping docs and code together). From other > projects of mine, this was the best way to obtain information about one > specific version, otherwise you'd have to keep a map like "revision X of code > corresponds to revision Y of documentation minus notes A, B and C"... I can tag the documentation at the time of release. However, the issue is that current documentation is often more accurate with respect to older versions than is the documentation in those older versions. But I just can't bring myself to go through the effort to backport documentation fixes. -- Ian Bicking | ia...@co... | http://blog.ianbicking.org |
From: Jorge G. <go...@ie...> - 2005-11-12 19:03:12
|
Ian Bicking <ia...@co...> writes: > I can tag the documentation at the time of release. However, the issue > is that current documentation is often more accurate with respect to > older versions than is the documentation in those older versions. But I > just can't bring myself to go through the effort to backport > documentation fixes. I am still in debt with you with regards to finding something to put docs in the code and using it for testing, as we've discussed a while ago. I'm sorry, but I've been too busy (and to make things "worse", I've subscribed to try getting my M.Sc. in electrical engineering ;-)) and couldn't put my hands on that. But, back to the point, I think that having newer docs more accurate is a natural consequence as is also the case with code. Small bugfixes make the intentions you (the SQLObject team and authors) had when you wrote the code. Small bugfixes to documentation make it clearer and more accurate with what the author tried saying. If this separation occurs, won't docs be left as secondary and lag behind the code too much? I'm a lot concerned with this lagging because there are already a lot of things that aren't clear in the docs and I think need being clarified. How to do that? My idea is writing a tutorial for starting -- I've started something for my own use and I don't feel it is in a publishing state not even as an 'alpha' release ;-) -- where people can see a few more complex use cases. Obviously the tutorial won't be enough to replace documentation, but it would be a nice complement to it and would link to the key points at the docs, filling some of the gaps I think are missing or need being make more clean and (why not?) more obvious... How I thought it: - start with actual docs (specially the Person class) - evolve them to make a sequence to create something like an address book, employees catalog, etc., including BLOB objects (employee photos, pictures from friends, something like that) - show how to create everything using SQLObject - show how to create an app using 'fromDatabase = True' - present basic operations in an ordered way: - INSERT - SELECT - UPDATE - DELETE - introduce transactions while working with two tables at the same time, with: - INSERT - UPDATE - DELETE - present how ForeignKey works and how it can be used to make the process of getting and updating data easier - present more "advanced" concepts: - getting the connection object to - execute arbitrary queries - (see if there's something interesting and that works with PostgreSQL + SQLite here) - use the connection hub in different files (more than one '.py' with code) - write some application that creates a session per user, allowing the use of database restrictions and policies to GRANT or not access to data This is an introductory and very simple tutorial, where people will be able to see more of SQLObject and see it in a "real world" application (at least it has a bit more of classes, and should be running at the end of the tutorial). At first I was thinking on making it simple, with no user interface at all, so that the developer that is following the tutorial can "glue" it to his/her favorite UI toolkit. And, since TurboGears is also a very interesting tool, and using it with SQLObject to write wep apps is very pleasant, I thought about using the first tutorial as a base for a second one, where a web interface written with TurboGears would be added to it. But this is another thing for my wishlist ;-) Sorry for missing the topic of your post... :-( -- Jorge Godoy <go...@ie...> |
From: Ian B. <ia...@co...> - 2005-11-12 21:12:57
|
Jorge Godoy wrote: > Ian Bicking <ia...@co...> writes: > > >>I can tag the documentation at the time of release. However, the issue >>is that current documentation is often more accurate with respect to >>older versions than is the documentation in those older versions. But I >>just can't bring myself to go through the effort to backport >>documentation fixes. > > > I am still in debt with you with regards to finding something to put docs in > the code and using it for testing, as we've discussed a while ago. I'm sorry, > but I've been too busy (and to make things "worse", I've subscribed to try > getting my M.Sc. in electrical engineering ;-)) and couldn't put my hands on > that. > > But, back to the point, I think that having newer docs more accurate is a > natural consequence as is also the case with code. Small bugfixes make the > intentions you (the SQLObject team and authors) had when you wrote the code. > Small bugfixes to documentation make it clearer and more accurate with what > the author tried saying. > > If this separation occurs, won't docs be left as secondary and lag behind the > code too much? I'm a lot concerned with this lagging because there are > already a lot of things that aren't clear in the docs and I think need being > clarified. I don't think so; this is intended to make the documentation easier to manage and update, not harder. I don't feel like managing branches when updating the documentation, so I'm not backporting documentation fixes. This is how it currently is. But I also don't want to put the trunk documentation up on the site, because it's not accurate with respect to 0.7. By changing to just one line of documentation -- primarily by noting in the docs to what version features were added -- there will only be a trunk for the documentation, and it will be the one best version of the documentation at all times. svn:externals can be used to keep the documentation appearing in checkouts; it's just that the docs/ directory will be pointing to the same place for all branches. The tutorial outline looks useful, and I hope you have a chance to do some work on it. -- Ian Bicking | ia...@co... | http://blog.ianbicking.org |
From: Ian B. <ia...@co...> - 2005-11-14 02:07:40
|
Ian Bicking wrote: > I'm thinking that documentation shouldn't be branched like other parts > of the code. This is now done, documentation is in http://svn.colorstudy.com/SQLObject/docs/ -- there's an svn:externals so that checkouts will still look the same. However, svn gets weird about directory deletes, so it's very possible that for current checkouts you'll have to rm -rf the docs directory and svn up to get the proper version. -- Ian Bicking | ia...@co... | http://blog.ianbicking.org |