On Fri, Oct 2, 2009 at 3:00 AM, Robert Bradshaw <[email protected]> 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. > > Completeness, especially of a moving target, is an ambitious but > important goal. Eventually we might consider Numpy's documentation approach and guidelines. Although Cython is not a library where an API is dominant, but instead a language, I think we might still glean an approach from them as to easy documentation updating... for constant completeness. > > [...] > >> 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... > > Though I think coming at things from a different angle is good, I > worry about having too many different overlapping components (from > both a maintenance and generation viewpoint). Oh yeah, +1, me too. Maybe an MVC type approach can be utilized. Let me investigate and think about this a little bit. Considering the api is not dominant to Cython users, reST inlined with the code source is not the right approach. > >> "Introduction To Cython" would be the overview and introduction >> including all sorts of introductory topics and links. > > Are you thinking more than a pageful of content, or would this > essentially be the front page of the documentation? (I'm leaning > towards the latter.) Yes, front page is certainly adequate. In fact I have no theoretical objection to an entire, single document structure either... I'm just rambling thoughts as I go. > >> "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. My attitude is whatever works best gets my support. My view point is from "the guy who wants an answer to a question NOW", and doesn't want to have to search forever to find it. However that is accomplished suits me greatly. Beyond that, I want what will be considered to work best for the subjective user. > >> "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 > to belong in a reference manual. Perhaps gotchas and caviats could go > here too. +1. Succinct, navigable, and complete... are the necessary requirements, imho. However that is best achieved is great. > >> "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. Agreed. I was just trying to solve a way to keep verbosity out of the ref guide. > >> "Videos and Webcasts" would be.. well this is self-explanatory... >> >> "White Papers" would be any pdf like documents available.. etc. > > These two would basically be aggregations of whatever comes up (like > the two recent SciPy proceedings submissions). We could probably put > a list of slides/talks there as well. > >> ..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. Yes, absolute embedding is crucial and +1 on the rest. > >> Lastly, of my thoughts for now is, the subject of "search portals". >> Common, current search technology is one of my pet-peeves in that a >> search lead you to a page and not to the item context within the page >> itself. To mitigate this hindrance, I think each topic should reside >> each within in its own page. Also, to accommodate my vision of >> inter-documentary documentation a global search engine will be needed. >> Xapian, could be considered.. it is exceptional with python bindings. >> Or google or what ever.. I defer. > > I personally hate tutorials where I have to keep clicking "next" > instead of scrolling down, but we could experiment with both. Another > note on this--the table of contents in the header of the page and > each section is quite bulky--it'd be nice to only have it in the > sidebar. Yes, I agree with "next-itus" too. I just want to figure out a way to eliminate the valuable time it takes to obtain a particular piece of information. How we get there should be our focus. So, thank you very much for all your input. ..As sort of an ironic side note... My model for decent navigable documentation has always been Trolltech/Nokia's Qt framework, which I just noticed will be re-designing their doc structure [1] . [1] http://labs.trolltech.com/blogs/2009/09/28/giving-the-doc-a-facelift/ ~Pete > > - Robert > > > _______________________________________________ > Cython-dev mailing list > [email protected] > http://codespeak.net/mailman/listinfo/cython-dev > _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
