From: Ian B. <ia...@co...> - 2003-01-25 04:27:32
|
Okay, I'm messing around with the document extractor again, and trying to document a specific class. The class has a lot of methods, and I'd like to categorize them. I've also been using blockquotes to represent the nesting of the methods in the class and the class in the module. So the text looks like: HTTPRequest =========== class `HTTPRequest(Request)`: The well-named `HTTPRequest` represents a single HTTP request. It is created by the `Application`, and belongs to a `Transaction`. It is created by `Transaction`. **Accessors** `transaction()`: The `Transaction` this request belongs to `setTransaction(trans)`: This method should be invoked after the transaction is created for this request. `time()`: Returns the time that the request was received, a timestamp (seconds from the epoch). Now, I'd like **Accessors** to actually be a header, like: Accessors --------- But I don't believe reST allows a header in a blockquote. **Accessors** isn't too bad, and I can still put in a link target, but the thing I *really* want is a table of contents. Though, as I realize it, I *really* want a table of contents that includes the function definitions, so it'd be like: HTTPRequest Accessors transaction setTransaction time So that's even further from what reST is doing. What might I do to achieve that kind of formating? A table of contents like that would be quite important. I'm also thinking about putting groups of modules together into a single document (mostly modules that contain classes that inherit from each other). As a reader I find this easier to navigate generally, and it makes references easier to handle. So the table of contents would become much more important in that case. -- Ian Bicking Colorstudy Web Development ia...@co... http://www.colorstudy.com PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7 4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241 |
From: David G. <go...@py...> - 2003-01-25 16:08:03
|
Ian Bicking wrote: > Okay, I'm messing around with the document extractor again, and trying > to document a specific class. The class has a lot of methods, and I'd > like to categorize them. I've also been using blockquotes to represent > the nesting of the methods in the class and the class in the module. Why use blockquotes? > Now, I'd like **Accessors** to actually be a header, like: > > Accessors > --------- > > But I don't believe reST allows a header in a blockquote. **Accessors** > isn't too bad, and I can still put in a link target, but the thing I > *really* want is a table of contents. So make it a header. Don't use blockquotes. > Though, as I realize it, I *really* want a table of contents that > includes the function definitions, so it'd be like: > > HTTPRequest > Accessors > transaction > setTransaction > time > > So that's even further from what reST is doing. What might I do to > achieve that kind of formating? A table of contents like that would be > quite important. Stop fighting the markup. ReStructuredText doesn't use indentation for large-scale structure, only for local constructs (lists etc.). If it sounds like a duck and acts like a duck, it's a duck. Use section structure, and the table of contents is easy, cross-references are easy. If you want the output to have indentation for each section level, you can do that in the stylesheet. Don't let style dictate structure. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: Ian B. <ia...@co...> - 2003-01-29 04:05:18
|
On Sat, 2003-01-25 at 10:10, David Goodger wrote: > Stop fighting the markup. ReStructuredText doesn't use indentation for > large-scale structure, only for local constructs (lists etc.). If it sounds > like a duck and acts like a duck, it's a duck. Use section structure, and > the table of contents is easy, cross-references are easy. > > If you want the output to have indentation for each section level, you can > do that in the stylesheet. Don't let style dictate structure. Okay, so now I'm doing that, without indentation. Except for functions/methods, where the actual docstring is indented, as in: `function_name(params)`: The docstring. Which probably won't cause any problem. But now I'm trying to get the functions in the table of contents. Now, I could make each function a title, like function_name(params): ********************** The docstring But I don't think I can get that to look like I want, even with fancy CSS. Not to mention that I don't know at what level (h1, h2, h3, etc) the function definition will be -- it's largely orthogonal to other structure. Hmm... what I'd really like is a directive, like: .. header:: function_name That would create an invisible sort of header, where it shows up in the TOC and is a link target, but isn't otherwise displayed. Of course, "function_name" always the name of the target, I've been using "ClassName.function_name". So something like: .. header:: function_name :anchor-name: ClassName.function_name Anyway, that's my initial thought. Maybe there's a different way to do this. Also, would there be a way to create a smaller TOC for a section? I'm thinking about putting several modules in one document, to make interlinking easier, to make the public interface easier to navigate (since the interface is made up of the methods from several classes that inherit from each other). It would be nice to have a TOC for each class, for instance. Thanks, Ian |
From: David G. <go...@py...> - 2003-01-29 20:17:22
|
[David Goodger] >> Stop fighting the markup. ReStructuredText doesn't use indentation >> for large-scale structure, only for local constructs (lists etc.). >> If it sounds like a duck and acts like a duck, it's a duck. Use >> section structure, and the table of contents is easy, >> cross-references are easy. >> >> If you want the output to have indentation for each section level, >> you can do that in the stylesheet. Don't let style dictate >> structure. [Ian Bicking] > Okay, so now I'm doing that, without indentation. Except for > functions/methods, where the actual docstring is indented, as in: > > `function_name(params)`: > The docstring. > > Which probably won't cause any problem. But now I'm trying to get > the functions in the table of contents. That construct is a definition list. If that's what you want, fine, but there's no support for adding it to the TOC. Also, did you intend literals (``) instead of interpreted text (`)? > Now, I could make each function a title, like > > function_name(params): > ********************** > > The docstring > > But I don't think I can get that to look like I want, even with > fancy CSS. What do you want it to look like? > Not to mention that I don't know at what level (h1, h2, h3, etc) > the function definition will be -- it's largely orthogonal to other > structure. Hmm... what I'd really like is a directive, like: > > .. header:: function_name > > That would create an invisible sort of header, where it shows up in > the TOC and is a link target, but isn't otherwise displayed. Of > course, "function_name" always the name of the target, I've been > using "ClassName.function_name". So something like: > > .. header:: function_name > :anchor-name: ClassName.function_name > > Anyway, that's my initial thought. Maybe there's a different way to > do this. I don't think this is a good approach. It smells like a kludge: too single-purpose to be worthwhile, and very magical. How would this translate into elements in the doctree? The doctree must remain self-consistent and style-free (as much as possible). Although I still suspect you're letting style dictate structure, I'll try to help you out. But we must recognize that there are limits to reStructuredText, beyond which we have to consider alternatives. ReStructuredText is aimed at ordinary documents; it's not suitable for some really creative graphic design exercises, and I don't think it should be. It seems that you're looking for finer-grained selectability, to be able to more precisely target styles. Currently we have two extremes: overly broad (a <div> element surrounds every section, but different "types" of sections are not distinct from each other), and overly precise (each <div> section element has a unique "id" attribute, which *could* be used in the stylesheet, but it would be a manual pain). Perhaps the "topic" directive would suit your purposes. See <http://docutils.sf.net/spec/rst/directives.html#topic>, and note that topics cannot contain subsections or subtopics. Currently, topics don't show up in the table of contents, but that could be remedied with a new option to the "contents" directive. As for "anchor-name", that can be a simple internal hyperlink target. Together, it would look something like this:: .. contents:: :topics: .. _ClassName.function.name: .. topic:: Docutils uses an optional "class" attribute on all elements, which is carried all the way through the HTML writer. The class attribute can contain multiple values (space-separated). A new directive could be added that adds a class value to the enclosing element, and this class could be selected in the stylesheet. If the section *containing* the specialized function sections is given a class, say "function-container", the stylesheet could contain a style like this:: div.function-container div { ... your styles here ... } I'll add these to the to-do list. Contributions are welcome! > Also, would there be a way to create a smaller TOC for a section? Yes, you can use the "contents" directive with the ":local:" option: Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled. The ":depth:" option may also be useful: The number of section levels that are collected in the table of contents. The default is unlimited depth. See <http://docutils.sf.net/spec/rst/directives.html#table-of-contents> for details, and <http://docutils.sf.net/spec/doctree.html> for examples of both options. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: Ian B. <ia...@co...> - 2003-01-30 00:49:40
|
On Wednesday, January 29, 2003, at 02:16 PM, David Goodger wrote: >> Now, I could make each function a title, like >> >> function_name(params): >> ********************** >> >> The docstring >> >> But I don't think I can get that to look like I want, even with >> fancy CSS. > > What do you want it to look like? I'm looking for something vaguely like the Python reference manual. I like the reference manuals for the most part, except they don't have very good indexes (which is something I really look forward to with docutils/reST). >> Not to mention that I don't know at what level (h1, h2, h3, etc) >> the function definition will be -- it's largely orthogonal to other >> structure. Hmm... what I'd really like is a directive, like: >> >> .. header:: function_name >> >> That would create an invisible sort of header, where it shows up in >> the TOC and is a link target, but isn't otherwise displayed. Of >> course, "function_name" always the name of the target, I've been >> using "ClassName.function_name". So something like: >> >> .. header:: function_name >> :anchor-name: ClassName.function_name >> >> Anyway, that's my initial thought. Maybe there's a different way to >> do this. > > I don't think this is a good approach. It smells like a kludge: too > single-purpose to be worthwhile, and very magical. How would this > translate into elements in the doctree? The doctree must remain > self-consistent and style-free (as much as possible). > > Although I still suspect you're letting style dictate structure, I'll > try to help you out. But we must recognize that there are limits to > reStructuredText, beyond which we have to consider alternatives. > ReStructuredText is aimed at ordinary documents; it's not suitable for > some really creative graphic design exercises, and I don't think it > should be. This is, or is supposed to be, the quintessential reStructuredText document -- a programmer's reference. If the doctree is nice, then with a little XSL or what-have-you anything is possible (though not necessarily easy even then). But the preprocessor already feels like a kludge, and adding a postprocessor feels even worse. But then I'm anti-XML, so I'd feel that way ;) I prefer event-driven to a tree representation, but whatever. And layout does really matter -- that's a big part of why I don't like the output of pydoc. I want the documentation to look right both in the source and in the generated documentation. It's not an unreasonable goal, and I don't think a difficult goal either. > It seems that you're looking for finer-grained selectability, to be > able to more precisely target styles. Currently we have two extremes: > overly broad (a <div> element surrounds every section, but different > "types" of sections are not distinct from each other), and overly > precise (each <div> section element has a unique "id" attribute, which > *could* be used in the stylesheet, but it would be a manual pain). > > Perhaps the "topic" directive would suit your purposes. See > <http://docutils.sf.net/spec/rst/directives.html#topic>, and note that > topics cannot contain subsections or subtopics. Currently, topics > don't show up in the table of contents, but that could be remedied > with a new option to the "contents" directive. Yes, topics look good. I just tried using them, and with a little CSS tweaking they seem alright. Though because of the use of <p> tags for the title and body, the function title and parameter line is separated from its docstring, which I would prefer not to have. I haven't seen anything that lets you change the space between paragraphs with CSS, which I've wanted to do often... > Docutils uses an optional "class" attribute on all elements, which is > carried all the way through the HTML writer. The class attribute can > contain multiple values (space-separated). A new directive could be > added that adds a class value to the enclosing element, and this class > could be selected in the stylesheet. If the section *containing* the > specialized function sections is given a class, say > "function-container", the stylesheet could contain a style like this:: > > div.function-container div { ... your styles here ... } > > I'll add these to the to-do list. Contributions are welcome! Yes, that would work nicely, because then I wouldn't have to monopolize topic:: for function definitions. I still haven't looked at the internals of the parsing, but I'll try to look into it more -- it might give me some insight into how the extractor should work as well. Ian |
From: Mark N. <no...@so...> - 2003-01-30 15:55:56
|
Ian Bicking wrote: > > On Wednesday, January 29, 2003, at 02:16 PM, David Goodger wrote: > >> Now, I could make each function a title, like > >> > >> function_name(params): > >> ********************** > >> > >> The docstring > >> > >> But I don't think I can get that to look like I want, even with > >> fancy CSS. > > > > What do you want it to look like? > > I'm looking for something vaguely like the Python reference manual. I > like the reference manuals for the most part, except they don't have > very good indexes (which is something I really look forward to with > docutils/reST). We discussed this issue a couple of weeks back, but what I'm planning to do for my index entries is to label them as inline targets (or explicit markup targets tied to inline targets) and have a separate writer that can extract them into a usable index. --Mark |
From: Ian B. <ia...@co...> - 2003-01-30 21:14:37
|
On Thu, 2003-01-30 at 09:52, Mark Nodine wrote: > > I'm looking for something vaguely like the Python reference manual. I > > like the reference manuals for the most part, except they don't have > > very good indexes (which is something I really look forward to with > > docutils/reST). > > We discussed this issue a couple of weeks back, but what I'm > planning to do for my index entries is to label them as > inline targets (or explicit markup targets tied to inline > targets) and have a separate writer that can extract them > into a usable index. Oops, I meant table of contents. But I want an index too! I want it all! ;) It seems it would be very easy to start with an index made up of all the targets in the document. I noticed some notes on something like `word`:index: which would also be possible, but probably more thorough than I'd use in programming documentation. -- Ian Bicking Colorstudy Web Development ia...@co... http://www.colorstudy.com PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7 4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241 |