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... 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). > "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.) > "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 to belong in a reference manual. Perhaps gotchas and caviats could go here too. > "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. > "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. > 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. - Robert _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
