1 Oct 09:09
1 Oct 09:21
Re: [Cython] Updating Documentation
On Thu, Oct 1, 2009 at 3:09 AM, Robert Bradshaw <robertwb@...> wrote: > BTW, who wants/needs push access to hg.cython.org/cython-docs? > (Though you can set up your own repos as well.) > > - Robert > > _______________________________________________ > Cython-dev mailing list > Cython-dev@... > http://codespeak.net/mailman/listinfo/cython-dev > Hi Robert. I have a branch repo at http://bitbucket.org/travlr/cython-docs . That should suffice for now, I'd think. Unless you all want it differently. At this point I've redone the super-structure and am iterating inward. Conciseness is my goal. Let me know, at any time, your thoughts or vision do not coincide with what I do..
2 Oct 03:39
Re: [Cython] Updating Documentation
On Oct 1, 2009, at 12:21 AM, Peter Alexander wrote: > Hi Robert. I have a branch repo at > http://bitbucket.org/travlr/cython-docs . That should suffice for now, > I'd think. Unless you all want it differently. Yes, that's totally fine. Distributed revision control is nice :) > At this point I've redone the super-structure and am iterating inward. > Conciseness is my goal. Let me know, at any time, your thoughts or > vision do not coincide with what I do.. Looks good. I think most of the language basics could be put later, with the exception of typing. So the first three sections could be overview, data typing, and compilation. After those three, we could move on to the topic-specific tutorials. - Robert
2 Oct 04:13
Re: [Cython] Updating Documentation
On Thu, Oct 1, 2009 at 9:39 PM, Robert Bradshaw <robertwb@...> wrote: > On Oct 1, 2009, at 12:21 AM, Peter Alexander wrote: > >> Hi Robert. I have a branch repo at >> http://bitbucket.org/travlr/cython-docs . That should suffice for now, >> I'd think. Unless you all want it differently. > > Yes, that's totally fine. Distributed revision control is nice :) > >> At this point I've redone the super-structure and am iterating inward. >> Conciseness is my goal. Let me know, at any time, your thoughts or >> vision do not coincide with what I do.. > > Looks good. I think most of the language basics could be put later, > with the exception of typing. So the first three sections could be > overview, data typing, and compilation. After those three, we could > move on to the topic-specific tutorials. > > - Robert > > _______________________________________________ > Cython-dev mailing list > Cython-dev@... > http://codespeak.net/mailman/listinfo/cython-dev > I look at what I'm working on now as a "reference guide" should be solely considered as a "get your fingers on the answer, quickly", guide.(Continue reading)
2 Oct 05:27
Re: [Cython] Updating Documentation
On Thu, Oct 1, 2009 at 10:13 PM, Peter Alexander <vel.accel@...> wrote: > On Thu, Oct 1, 2009 at 9:39 PM, Robert Bradshaw > <robertwb@...> wrote: >> On Oct 1, 2009, at 12:21 AM, Peter Alexander wrote: >> >>> Hi Robert. I have a branch repo at >>> http://bitbucket.org/travlr/cython-docs . That should suffice for now, >>> I'd think. Unless you all want it differently. >> >> Yes, that's totally fine. Distributed revision control is nice :) >> >>> At this point I've redone the super-structure and am iterating inward. >>> Conciseness is my goal. Let me know, at any time, your thoughts or >>> vision do not coincide with what I do.. >> >> Looks good. I think most of the language basics could be put later, >> with the exception of typing. So the first three sections could be >> overview, data typing, and compilation. After those three, we could >> move on to the topic-specific tutorials. >> >> - Robert >> >> _______________________________________________ >> Cython-dev mailing list >> Cython-dev@... >> http://codespeak.net/mailman/listinfo/cython-dev >> > > I look at what I'm working on now as a "reference guide" should be > solely considered as a "get your fingers on the answer, quickly",(Continue reading)
2 Oct 06:46
Re: [Cython] Updating Documentation
On Thu, Oct 1, 2009 at 11:27 PM, Peter Alexander <vel.accel@...> wrote: > On Thu, Oct 1, 2009 at 10:13 PM, Peter Alexander <vel.accel@...> wrote: >> On Thu, Oct 1, 2009 at 9:39 PM, Robert Bradshaw >> <robertwb@...> wrote: >>> On Oct 1, 2009, at 12:21 AM, Peter Alexander wrote: >>> >>>> Hi Robert. I have a branch repo at >>>> http://bitbucket.org/travlr/cython-docs . That should suffice for now, >>>> I'd think. Unless you all want it differently. >>> >>> Yes, that's totally fine. Distributed revision control is nice :) >>> >>>> At this point I've redone the super-structure and am iterating inward. >>>> Conciseness is my goal. Let me know, at any time, your thoughts or >>>> vision do not coincide with what I do.. >>> >>> Looks good. I think most of the language basics could be put later, >>> with the exception of typing. So the first three sections could be >>> overview, data typing, and compilation. After those three, we could >>> move on to the topic-specific tutorials. >>> >>> - Robert >>> >>> _______________________________________________ >>> Cython-dev mailing list >>> Cython-dev@... >>> http://codespeak.net/mailman/listinfo/cython-dev >>> >>(Continue reading)
2 Oct 09:00
Re: [Cython] Updating Documentation
On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: > I look at what I'm working on now as a "reference guide" should be > solely considered as a "get your fingers on the answer, quickly", > guide. > > Basically, what I'm thinking of for this, is a very complete outline > stating the language rules, particulars, etc., with cross-references > galore, indexing, and lots of examples, etc., OK, that helps me see more where you're coming from. I think the two papers we have are more of the tutorial style, but have a lot of good material in them. > So.. personally I am invested in the reference type, but I totally > think that domain specific tutorials would be great for Cython to > support. And a necessity, you might say. > > But, for now I'd like to concentrate on making the ref guide succinct, > accessible, and most of all... complete. Completeness, especially of a moving target, is an ambitious but important goal. [...] > I think that there should possibly be something like this posted on > the documentation section of the static Cython portal page: > "Introduction To Cython", "Tutorials", "Reference Guide", "User > Guide", "Videos and WebCasts", "White Papers", etc...(Continue reading)
2 Oct 09:51
Re: [Cython] Updating Documentation
On Fri, Oct 2, 2009 at 3:00 AM, Robert Bradshaw <robertwb@...> wrote: > On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: > >> I look at what I'm working on now as a "reference guide" should be >> solely considered as a "get your fingers on the answer, quickly", >> guide. >> >> Basically, what I'm thinking of for this, is a very complete outline >> stating the language rules, particulars, etc., with cross-references >> galore, indexing, and lots of examples, etc., > > OK, that helps me see more where you're coming from. I think the two > papers we have are more of the tutorial style, but have a lot of good > material in them. I think there is excellent material in them. I'm just the kind of guy who only likes to read through verbosity when I want to, not that I should have to.. in order to get to the vital piece of information I'm striving to find at that moment. This is personal peeve that is general to all information retrieval and should not be considered specific to anything here. > >> So.. personally I am invested in the reference type, but I totally >> think that domain specific tutorials would be great for Cython to >> support. And a necessity, you might say. >> >> But, for now I'd like to concentrate on making the ref guide succinct, >> accessible, and most of all... complete.(Continue reading)
2 Oct 10:03
Re: [Cython] Updating Documentation
Peter Alexander wrote: > Considering the api is not dominant to Cython users, reST inlined with > the code source is not the right approach. Well, the examples are there to present Cython code. I don't see how this makes inlined code the wrong approach. It even has the advantage of allowing to split the code around explanatory text sections. The only problem I see is that it's harder to test as doctest doesn't currently work for Cython code. But that could be helped by extracting the code from the document into a module first. The problem I see with an MVC approach (I assume you considered writing the example code with text injection hooks) is that they'd loose the context. The examples don't make much sense without the surrounding text that explains what's interesting about them. And if they do, they may not be good examples in the first place, as they're likely too broad. Stefan
2 Oct 09:59
Re: [Cython] Updating Documentation
Robert Bradshaw wrote: > On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: > > >> "Tutorials" would be a self contained sphinx doc with a TOC that >> includes tutorials of general, topic and domain specific "dive-in and >> get your hair wet" material. Here we "hold the reader's hand" and walk >> them through usage. >> > > I could see this expanding into the bulk of the documentation, with > 2-4 "getting started" sections, and then numerous independent > chapters after that as previously mentioned in this thread. > > Another option is making tutorials like short "quick starts" with the > bulk of the meat in the reference manual. I'm leaning against this, > but would like feedback. > > >> "Reference Guide" would be an elaborate "outline" of facts. Used for >> fast access to succinct information. >> > > I could see this containing things such as the list of all compiler > directives, syntax particulars, list of builtin types and > optimizations, differences between Python and Cython and other stuff > that does not fit into a tutorial-like nature. Stuff like buffers > should have an entry here, with syntax and a brief overview of how > they work and what they're for, with a link to the tutorial section > for more. How to use them to accomplish different things doesn't seem(Continue reading)
2 Oct 10:16
Re: [Cython] Updating Documentation
Dag Sverre Seljebotn wrote: > Robert Bradshaw wrote: > >> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >> >> >>> ..Now, All examples/snippets should be global, in its own directory, >>> so each documentation can "embed" the example it needs. Hell.. if we >>> were sophisticated one day.. video snippets might also be "embedded" >>> or at least linked to. >>> >>> >> Does sphinx have the ability to embed external code snippets? I think >> it's important to have actual snippets in the documentation itself, >> ideally with links to 1. entire working program directories (complete >> with build scripts) 2. Annotated (-a html output) versions and 3. >> Sage notebooks (to make it easy to try out and play with while you're >> reading the documentation) and 4. somewhere that we can run >> regression tests on. >> >> > The matplotlib project has very good experience with some exciting stuff > that's kind of related (their entire web page is made with Sphinx). They > wrote a plugin to sphinx for a new code block tag (in the rst file in > the documentation). When encountered, Sphinx a) presents the code as > syntax-highlighted Python, b) executes the code and retrieves the > generated plot and present it. > > By adapting such a plugin for our needs, a special tag can be used to > embed Cython code, which at least syntax-highlights and makes "cython(Continue reading)
2 Oct 10:32
Re: [Cython] Updating Documentation
On Fri, Oct 2, 2009 at 4:16 AM, Dag Sverre Seljebotn <dagss@...> wrote: > Dag Sverre Seljebotn wrote: >> Robert Bradshaw wrote: >> >>> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >>> >>> >>>> ..Now, All examples/snippets should be global, in its own directory, >>>> so each documentation can "embed" the example it needs. Hell.. if we >>>> were sophisticated one day.. video snippets might also be "embedded" >>>> or at least linked to. >>>> >>>> >>> Does sphinx have the ability to embed external code snippets? I think >>> it's important to have actual snippets in the documentation itself, >>> ideally with links to 1. entire working program directories (complete >>> with build scripts) 2. Annotated (-a html output) versions and 3. >>> Sage notebooks (to make it easy to try out and play with while you're >>> reading the documentation) and 4. somewhere that we can run >>> regression tests on. >>> >>> >> The matplotlib project has very good experience with some exciting stuff >> that's kind of related (their entire web page is made with Sphinx). They >> wrote a plugin to sphinx for a new code block tag (in the rst file in >> the documentation). When encountered, Sphinx a) presents the code as >> syntax-highlighted Python, b) executes the code and retrieves the >> generated plot and present it. >>(Continue reading)
2 Oct 10:46
Re: [Cython] Updating Documentation
Peter Alexander wrote: > On Fri, Oct 2, 2009 at 4:16 AM, Dag Sverre Seljebotn > <dagss@...> wrote: > >> Dag Sverre Seljebotn wrote: >> >>> Robert Bradshaw wrote: >>> >>> >>>> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >>>> >>>> >>>> >>>>> ..Now, All examples/snippets should be global, in its own directory, >>>>> so each documentation can "embed" the example it needs. Hell.. if we >>>>> were sophisticated one day.. video snippets might also be "embedded" >>>>> or at least linked to. >>>>> >>>>> >>>>> >>>> Does sphinx have the ability to embed external code snippets? I think >>>> it's important to have actual snippets in the documentation itself, >>>> ideally with links to 1. entire working program directories (complete >>>> with build scripts) 2. Annotated (-a html output) versions and 3. >>>> Sage notebooks (to make it easy to try out and play with while you're >>>> reading the documentation) and 4. somewhere that we can run >>>> regression tests on. >>>> >>>> >>>>(Continue reading)
2 Oct 10:55
Re: [Cython] Updating Documentation
On Fri, Oct 2, 2009 at 4:46 AM, Dag Sverre Seljebotn <dagss@...> wrote: > Peter Alexander wrote: >> On Fri, Oct 2, 2009 at 4:16 AM, Dag Sverre Seljebotn >> <dagss@...> wrote: >> >>> Dag Sverre Seljebotn wrote: >>> >>>> Robert Bradshaw wrote: >>>> >>>> >>>>> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >>>>> >>>>> >>>>> >>>>>> ..Now, All examples/snippets should be global, in its own directory, >>>>>> so each documentation can "embed" the example it needs. Hell.. if we >>>>>> were sophisticated one day.. video snippets might also be "embedded" >>>>>> or at least linked to. >>>>>> >>>>>> >>>>>> >>>>> Does sphinx have the ability to embed external code snippets? I think >>>>> it's important to have actual snippets in the documentation itself, >>>>> ideally with links to 1. entire working program directories (complete >>>>> with build scripts) 2. Annotated (-a html output) versions and 3. >>>>> Sage notebooks (to make it easy to try out and play with while you're >>>>> reading the documentation) and 4. somewhere that we can run >>>>> regression tests on. >>>>>(Continue reading)
2 Oct 11:06
Re: [Cython] Updating Documentation
On Oct 2, 2009, at 1:46 AM, Dag Sverre Seljebotn wrote: > Peter Alexander wrote: >> >> Putting my creative hat on... >> >> Would be nice to just be able to toss "chunks" of information into a >> directory pool, that can be automatically structured to a view, by a >> "documentation structure model"? >> >> That way upkeep could be made more simple because all you'd have to >> worry about is tossing in the "chunk". >> >> That's kind of what I mean by an MVC model. It almost sounds like you want a big glorified index. (I'm not saying that's a bad thing, and it certainly would fit your bill of being able to look stuff up fast.) > OK, I see where you are coming from. As usual my suggestions are > mostly > with tutorials in mind. > > Other projects can do this in a great way by making the docstrings in > the codebase their chunks. We do that in Sage and it works very well--the reference manual is thousands of pages long, nearly all from function docstrings. > That doesn't *quite* all the time with(Continue reading)
2 Oct 11:09
Re: [Cython] Updating Documentation
> > > We do that in Sage and it works very well--the reference manual is > thousands of pages long, nearly all from function docstrings. > >> That doesn't *quite* all the time with >> Cython, but I think it could work great in some types of situations. >> >> Experiment: >> >> class WraparoundDirective(CompilerDirective): # in Options.py >> """ >> wraparound >> >> information about the wraparound compiler directive >> """ >> >> class ForInStatNode(Node): # In Nodes.py >> """ >> Python-style for-loop >> >> more info >> >> TAGS: pythoncompatible, loops >> """ >> >> >> Some transforms would fit for documenting language features as well: >> >> class ForloopOptimizations(CythonTransform):(Continue reading)
2 Oct 11:13
Re: [Cython] Updating Documentation
Robert Bradshaw wrote: > On Oct 2, 2009, at 1:46 AM, Dag Sverre Seljebotn wrote: > > >> Peter Alexander wrote: >> >>> Putting my creative hat on... >>> >>> Would be nice to just be able to toss "chunks" of information into a >>> directory pool, that can be automatically structured to a view, by a >>> "documentation structure model"? >>> >>> That way upkeep could be made more simple because all you'd have to >>> worry about is tossing in the "chunk". >>> >>> That's kind of what I mean by an MVC model. >>> > > It almost sounds like you want a big glorified index. (I'm not saying > that's a bad thing, and it certainly would fit your bill of being > able to look stuff up fast.) > > >> OK, I see where you are coming from. As usual my suggestions are >> mostly >> with tutorials in mind. >> >> Other projects can do this in a great way by making the docstrings in >> the codebase their chunks. >>(Continue reading)
2 Oct 11:25
Re: [Cython] Updating Documentation
On Fri, Oct 2, 2009 at 5:13 AM, Dag Sverre Seljebotn <dagss@...> wrote: > Robert Bradshaw wrote: >> On Oct 2, 2009, at 1:46 AM, Dag Sverre Seljebotn wrote: >> >> >>> Peter Alexander wrote: >>> >>>> Putting my creative hat on... >>>> >>>> Would be nice to just be able to toss "chunks" of information into a >>>> directory pool, that can be automatically structured to a view, by a >>>> "documentation structure model"? >>>> >>>> That way upkeep could be made more simple because all you'd have to >>>> worry about is tossing in the "chunk". >>>> >>>> That's kind of what I mean by an MVC model. >>>> >> >> It almost sounds like you want a big glorified index. (I'm not saying >> that's a bad thing, and it certainly would fit your bill of being >> able to look stuff up fast.) >> >> >>> OK, I see where you are coming from. As usual my suggestions are >>> mostly >>> with tutorials in mind. >>> >>> Other projects can do this in a great way by making the docstrings in(Continue reading)
2 Oct 11:29
Re: [Cython] Updating Documentation
On Fri, Oct 2, 2009 at 5:25 AM, Peter Alexander <vel.accel@...> wrote: > On Fri, Oct 2, 2009 at 5:13 AM, Dag Sverre Seljebotn > <dagss@...> wrote: >> Robert Bradshaw wrote: >>> On Oct 2, 2009, at 1:46 AM, Dag Sverre Seljebotn wrote: >>> >>> >>>> Peter Alexander wrote: >>>> >>>>> Putting my creative hat on... >>>>> >>>>> Would be nice to just be able to toss "chunks" of information into a >>>>> directory pool, that can be automatically structured to a view, by a >>>>> "documentation structure model"? >>>>> >>>>> That way upkeep could be made more simple because all you'd have to >>>>> worry about is tossing in the "chunk". >>>>> >>>>> That's kind of what I mean by an MVC model. >>>>> >>> >>> It almost sounds like you want a big glorified index. (I'm not saying >>> that's a bad thing, and it certainly would fit your bill of being >>> able to look stuff up fast.) >>> >>> >>>> OK, I see where you are coming from. As usual my suggestions are >>>> mostly >>>> with tutorials in mind. >>>>(Continue reading)
2 Oct 12:06
Re: [Cython] Updating Documentation
Peter Alexander wrote: > On Fri, Oct 2, 2009 at 5:25 AM, Peter Alexander wrote: >> On Fri, Oct 2, 2009 at 5:13 AM, Dag Sverre Seljebotn wrote: >>> Robert Bradshaw wrote: >>>> No offense intended (as this was clearly marked as an experiment) but >>>> I have to admit this feels rather contrived, especially if we end up >>>> making classes/structuring code just to hold the docstrings of user- >>>> level abstractions. +1 >>>> I think it would lead to a sparse scattering of >>>> documentation throughout the codebase (most of the code does *not* >>>> need to be exposed to the user documentation, e.g. all the Nodes that >>>> represent Python nodes, and most transforms). The comments/doctests >>>> in the code should probably be about the code itself (useful to a >>>> cython developer, but probably not to a cython user). >>>> >>> You may be right. (The one advantage is that it makes it easy to have >>> documentation for different versions of Cython.). That's an orthogonal problem and I find it unlikely that we will ever have to manage so many different Cython versions that the documentation becomes a bottleneck. >>> Thing is I need to have some "way of entry" into writing documentation >>> -- I must either think about the code that implements the feature, or >>> how I'd "tell people about it" directly in the docs. A pure MVC doesn't >>> give me that I think -- it would tend to just be another hierarchy to(Continue reading)
2 Oct 10:56
Re: [Cython] Updating Documentation
On Oct 2, 2009, at 12:59 AM, Dag Sverre Seljebotn wrote: > Robert Bradshaw wrote: >> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >> >>> "User Guide" would essentially be the reference guide outline but in >>> paragraph form which includes more detailed info, caveats, gotchas. >>> This would help keep the ref guide succinct in that "detail" can be >>> linked to from that document to this document (as well as tutorial >>> sections, etc..) >> >> This section seems redundant with tutorial + reference guide. >> > I think that it would not be entirely redundant; some other projects > have user guides and it tends to work well. However it is a > question of > how much we are able to do -- even creating it is a lot of work, but > (much worse) then it has to be maintained for years to come too. > > So I agree that we should avoid this one, at least until the other > points on the list are done. I should clarify--I imagine our "tutorials" to have somewhat of a users guide feel (as opposed to a task solving feel). > The matplotlib project has very good experience with some exciting > stuff > that's kind of related (their entire web page is made with Sphinx). > They > wrote a plugin to sphinx for a new code block tag (in the rst file in(Continue reading)
2 Oct 11:06
Re: [Cython] Updating Documentation
Robert Bradshaw wrote: > On Oct 2, 2009, at 12:59 AM, Dag Sverre Seljebotn wrote: > > > > >> I must say I'm really keen on having code snippets embedded into ReST >> text (and rather automatically exported as files), rather than the >> other >> way around. >> > > > Me too. I like your example of using :hidden and constructing whole > files--I didn't know you could do that. Sounds perfect (for the > tutorials at least). > Basically I think you are just fed everything (arguments + body) of a ReST tag, and are expected to supply a replacement ReST string. So you can do anything. Worst-case sceneario, two passes through the docs would be needed, one to create the whole file...I don't know, but that's not too horrible. So I just invented something. Come to think of it, I'd like #SHOW, #HIDE and #SNIP instructions in Cython source instead so that the number of ReST tags can be reduced. Dag Sverre
RSS Feed