Howdy folks --
FYI, I'm rapidly gaining ground on this big task. There's a lot to be
done, but I've got about half a dozen patches in my inbox, and I'm
going to keep pushing into next week. If anyone wants to start helping
tomorrow, here's some quick pointers:
How-to: http://tinyurl.com/68k7cb
R
On Apr 13, 9:48 pm, Malcolm Tredinnick <[EMAIL PROTECTED]>
wrote:
> On Sun, 2008-04-13 at 18:43 -0700, holdenweb wrote:
[...]
> > How long do we have to wait for the "master plan" to be revealed?
[...]
> ... about minus three or four days from now. :-)
>
> For example, one of the links Jacob pos
On Sun, 2008-04-13 at 18:43 -0700, holdenweb wrote:
> I've actually been looking for accepted documentation bugs as a
> starting-point for my Django development work, but most of them seem
> to be point issues. In the face of Jacob's promise (threat?) to
> radically revise the structure and natur
I've actually been looking for accepted documentation bugs as a
starting-point for my Django development work, but most of them seem
to be point issues. In the face of Jacob's promise (threat?) to
radically revise the structure and nature of the documentation I am
unsure what value these point edi
On Apr 4, 11:06 am, Fredrik Lundh <[EMAIL PROTECTED]> wrote:
> (docstrings occupy memory too, so if you're *only* writing for folks
> reading the source, use comments.)
And of course, a production environment can always optimize the doc
strings out.
--~--~-~--~~~---~
On Apr 2, 12:26 pm, "Marty Alchin" <[EMAIL PROTECTED]> wrote:
> def get_object_from_cache(self, ...):
> """
> Get an object from the cache and return it.
>
> ...
hmm... the doc string equivalent of the infamous c inanity:
i++ // increment i
I have seen a bit of that in the c
On Fri, Apr 4, 2008 at 12:39 PM, Adam <[EMAIL PROTECTED]> wrote:
> Apologies in advance if this is out of scope of the discussion here,
> but I just wanted to make sure that the existing documentation for
> django 0.91 [1] isn't lost in the shuffle.
It won't. I'll probably just flatten what's
Apologies in advance if this is out of scope of the discussion here,
but I just wanted to make sure that the existing documentation for
django 0.91 [1] isn't lost in the shuffle. It appears that this
documentation is at least somewhat outside the process of the rest of
the documentation (0.95, 0.9
Jacob Kaplan-Moss wrote:
> That's probably the best idea. We'd still need an editor to eye
> submissions, remove outdated or missing material, brow-beat authors
> into updating blog entries, etc.
Just make sure you make it possible for external editors (=anyone) to
maintain link collections, an
On Fri, Apr 4, 2008 at 9:17 AM, Fredrik Lundh <[EMAIL PROTECTED]> wrote:
> I haven't checked if Sphinx already supports this, but one of the core
> ideas for the Python AltLibRef project that partially inspired Sphinx
> was a simple "target" concept that could be used to link to very
> specifi
On Fri, Apr 4, 2008 at 9:04 AM, Fredrik Lundh <[EMAIL PROTECTED]> wrote:
> A compromise would be centralized core documentation, but with links to
> external sites in a clearly-marked "see also" section. The web *is* a
> distributed place, after all.
That's probably the best idea. We'd still
Jacob Kaplan-Moss wrote:
> Like James and Marty I'm skeptical that it'll be useful all that
> often. docstrings are really meant for folks reading the source
nah, they're meant for folks using the "help" command when playing with
things via the command line (or using similar mechanisms in smart
Alex Myodov wrote:
> Breaking the huge documents into smaller chunks for readability is
> good... but please do leave the original huge ones as well! There are
> cases where "a huge document" serves more help than "a bunch of
> smaller ones" and really has its worth.
I haven't checked if Sphinx
Jacob Kaplan-Moss wrote:
>> I'm wondering if something like http://django.reddit.com/ shouldn't
>> get some sort of official blessing for listing/searching those blog
>> posts which aren't of good enough quality for inclusion in the
>> official docs, but are still useful to some people.
>
>
Sorry, as usual, I wasn't clear. When I said "at least in part" I
didn't express my thoughts very well.
I don't mean that high level or in depth discussion should be taking
place in the doc strings, that's for your excellent blog posts (and
the docs, of course)!.
But it doesn't hurt to have cla
> Once the refactor is complete we can start looking at writing new stuff.
Sorry, posted my last message before seeing this.
--~--~-~--~~~---~--~~
You received this message because you are subscribed to the Google Groups
"Django developers" group.
To post to this
> While I agree with the importance of having reusability tips, I would
> certainly argue against putting it anywhere near django.contrib. When
> I started working on my first app, I had unnecessary delusions of
> getting into django.contrib when it was ready. I wouldn't want to
> cause more peopl
On Wed, Apr 2, 2008 at 5:58 PM, SmileyChris <[EMAIL PROTECTED]> wrote:
> I'd suggest moving install to a how-to rather than a topical guide.
> Perhaps deployment could go under there, too? They seem closely
> related.
So the idea is that "topics" are for focused, core topical guides;
"how-tos"
On Wed, Apr 2, 2008 at 6:05 PM, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote:
> One thing that struck me while looking over this list is that it might
> be a good idea to add a section on best practices for writing reusable
> apps. James Bennett's presentation at PyCon hit on some really good
>
On Wed, Apr 2, 2008 at 7:05 PM, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote:
> One thing that struck me while looking over this list is that it might
> be a good idea to add a section on best practices for writing reusable
> apps. James Bennett's presentation at PyCon hit on some really good
>
Looks really good--a lot cleaner and better laid out than the current
docs!
One thing that struck me while looking over this list is that it might
be a good idea to add a section on best practices for writing reusable
apps. James Bennett's presentation at PyCon hit on some really good
main point
I'd suggest moving install to a how-to rather than a topical guide.
Perhaps deployment could go under there, too? They seem closely
related.
--~--~-~--~~~---~--~~
You received this message because you are subscribed to the Google Groups
"Django developers" group.
T
Hi folks --
I've finished making a new outline for the documentation based on my
proposal I posted last week. It's available online:
HTML: http://toys.jacobian.org/django/new-docs-outline/
OPML: http://toys.jacobian.org/django/new-docs-outline.opml
OmniOutliner: http://toys.jacobian.
On Wed, Apr 2, 2008 at 10:47 AM, AmanKow <[EMAIL PROTECTED]> wrote:
> Will the api and internals references be generated (at least in part)
> via doc string extraction? That's a big plus to me.
When appropriate we could; Sphinx does that, too:
http://sphinx.pocoo.org/ext/autodoc.html
Like Jam
On Wed, Apr 2, 2008 at 12:22 PM, James Bennett <[EMAIL PROTECTED]> wrote:
> I most sincerely hope not; unless you're like me and write short-form
> novels in your docstrings, they tend to be an absolutely horrible
> source of end-user documentation.
def get_object_from_cache(self, ...):
""
On Wed, Apr 2, 2008 at 10:47 AM, AmanKow <[EMAIL PROTECTED]> wrote:
> Will the api and internals references be generated (at least in part)
> via doc string extraction? That's a big plus to me.
I most sincerely hope not; unless you're like me and write short-form
novels in your docstrings, the
Will the api and internals references be generated (at least in part)
via doc string extraction? That's a big plus to me.
On Mar 31, 2:45 pm, "Jacob Kaplan-Moss" <[EMAIL PROTECTED]>
wrote:
> I'm embarking on a mission to refactor Django's documentation; this is where
> you give me feedback about
On Tue, Apr 1, 2008 at 7:41 AM, Russell Keith-Magee
<[EMAIL PROTECTED]> wrote:
> * Existing permalinks need to be preserved in some fashion, if only
> so that the archive of answers in django-users continues to be a
> useful resource.
It'll be tough. The worst part about anchors is that they
On Mon, Mar 31, 2008 at 7:48 PM, James Bennett <[EMAIL PROTECTED]> wrote:
> The next release will have 'M-x copyeditor' for that, actually...
See, this is why I like to mention Emacs 'round here; I can always
count on James for the follow-up. I'll tell you what, though, "M-x
copyeditor" would *t
On Mon, Mar 31, 2008 at 7:47 PM, pbx <[EMAIL PROTECTED]> wrote:
> Second, I take and agree with your point about editorial authority.
> Leaving aside the question of outside resources, I wonder if some
> pathway for user feedback or annotation of the official docs, in
> addition to the ticket
On Mar 31, 7:45 pm, "Jacob Kaplan-Moss" <[EMAIL PROTECTED]>
wrote:
> I'm embarking on a mission to refactor Django's documentation;
Great! I'll be happy to help out with some of the grunt work as and
when
I can find a spare moment.
> * Beginner material: we've got a good amount if this in t
> So feedback is welcome, please give it.
Breaking the huge documents into smaller chunks for readability is
good... but please do leave the original huge ones as well! There are
cases where "a huge document" serves more help than "a bunch of
smaller ones" and really has its worth.
Opening /cache/
On 01/04/2008, at 2:45 AM, Jacob Kaplan-Moss wrote:
>
> I'm embarking on a mission to refactor Django's documentation; this
> is where
> you give me feedback about how much crack I'm smoking. Keep in mind
> that most
> of this post fits into the "heads-up" category: if I'm not asking
> for
On Mon, Mar 31, 2008 at 7:25 PM, Jacob Kaplan-Moss
<[EMAIL PROTECTED]> wrote:
> Technology helps in some places, but there's no replacement
> for a good editor. And I'm *not* talking about Emacs.
The next release will have 'M-x copyeditor' for that, actually...
--
"Bureaucrat Conrad, you are
On Mar 31, 8:25 pm, "Jacob Kaplan-Moss" <[EMAIL PROTECTED]>
wrote:
> On Mon, Mar 31, 2008 at 6:25 PM, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote:
> > I'm wondering if something likehttp://django.reddit.com/shouldn't
> > get some sort of official blessing for listing/searching those blog
> > po
On Mon, Mar 31, 2008 at 6:25 PM, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote:
> I'm wondering if something like http://django.reddit.com/ shouldn't
> get some sort of official blessing for listing/searching those blog
> posts which aren't of good enough quality for inclusion in the
> official
On Mon, Mar 31, 2008 at 4:36 PM, [EMAIL PROTECTED]
<[EMAIL PROTECTED]> wrote:
> One thing I'm trying to figure out in my small set of docs is how
> frequently I want/plan to use the index and glossary functionality
> that comes with sphinx. How much additional meta data do you hope to
> add to
This all sounds really awesome!
> * Cross-sectional how-tos: we've only got a few of these currently. This
> is the area where bloggers are doing a wonderful job these days. The
> problem with this blog material is that it usually doesn't every get
> updated, so it eventuall
I won't bother responding to anybody in particular, because I'm in
agreement with so many on this thread so far. I'm glad to see this
refactoring happen, because a doc improvement can only make things
better for everybody.
I know you're not getting into details yet, but once you do get down
to it
On Mon, 2008-03-31 at 13:45 -0500, Jacob Kaplan-Moss wrote:
[...]
> * Internals: not so hot; in fact, we've really only got the contributing
> document. Help is needed here.
There's http://code.djangoproject.com/wiki/DevModelCreation. It needs to
be updated when model inheritance lands
I've been looking at using the sphinx tools for overhauling the
Satchmo documentation too. There's far far less documentation in that
project so it is easier but I am anxious to see how you do it. IMHO,
Django really has some best practices with documentation so I
appreciate the fact that you're k
On Mon, Mar 31, 2008 at 4:01 PM, J. Cliff Dyer <[EMAIL PROTECTED]> wrote:
> Since all the documentation is already in subversion, it might make
> sense to have a docs-refactor branch on the tree.
I'd rather not -- I don't want to get sucked into thinking I have a
long time for this. As long as
On Mon, Mar 31, 2008 at 2:29 PM, Tim Chase
<[EMAIL PROTECTED]> wrote:
> Ah, the curse of backwards compatibility and permalinks. My one
> concern (okay, given more time to think about it, perhaps more
> will percolate to the surface) with this is the abundance of
> (legacy) HTML-fragment refe
On Mon, 2008-03-31 at 13:45 -0500, Jacob Kaplan-Moss wrote:
> Right. How will I do this, you say? Here's my plan:
>
> * Using the outline from the existing documentation
> (http://toys.jacobian.org/django/docoutline-r7392/), make a new outline
> and figure out where each bit fits
Tim Chase wrote:
> Ah, the curse of backwards compatibility and permalinks. My one
> concern (okay, given more time to think about it, perhaps more
> will percolate to the surface) with this is the abundance of
> (legacy) HTML-fragment references that reside in the ML archives,
> such as
>ht
> Am I missing anything here?
>
> So feedback is welcome, please give it.
Ah, the curse of backwards compatibility and permalinks. My one
concern (okay, given more time to think about it, perhaps more
will percolate to the surface) with this is the abundance of
(legacy) HTML-fragment references
I like it, the problem becomes a bit more obvious if you look at
something like the templates for developers page, which is pretty
messy and contains a lot of different topics, or something like the
newoforms docs, which are just huge and could probably do to be broken
down a lot. And of course,
I'm embarking on a mission to refactor Django's documentation; this is where
you give me feedback about how much crack I'm smoking. Keep in mind that most
of this post fits into the "heads-up" category: if I'm not asking for feedback
on some point it's because I've made up my mind. Only argue with
48 matches
Mail list logo
