search

abathur / ldmud-doc

A temporary repo for working on a revamp of the documentation system for http://github.com/ldmud/ldmud
0 stars 0 forks source link

synopsis grouping #7

Closed abathur closed 8 years ago

abathur commented 9 years ago

Some documents (for example: https://github.com/ldmud/ldmud/blob/master/doc/efun/allocate) create one or more "groups" of synopsis by using a blank line to separate them; typically they are grouped by the first argument.

This behavior can't really be preserved in the source with sphinx. The arguments to the directive for documenting the function end at the first blank line. I think there are three options:

  1. Treat this as non-essential and ignore it.
  2. Instead of using a fully-blank line, separate the synopses with a code comment (this is the manual way).
  3. Do some additional programming to add a heuristic that our sphinx extension uses to decide when to visibly group synopsis lines, and how to do so.

My personal thinking is the that the blank line doesn't really communicate much semantically and isn't worth preserving. If you support option 3, please discuss your thoughts on what heuristics could be used to decide between presenting the synopses with/out groups, and which ones could be used to decide what the groups are.

abathur commented 8 years ago

I'm going to selflishly decide on the one that requires the least amount of work for now (1) with the knowledge that it shouldn't be too hard to backstop it with the code-comment version (2).