On Nov 17, 2013, at 1:43 PM, Leif Hedstrom <[email protected]> wrote: >> >> >> Everything in reference/ produces a man page. > > Does it also create a man page or link for every function? I’m definitely not > an expert on man pages, but I’m fairly certain it’s a common pattern to allow > “man TSAnyFunction” and the page which has relevant info for that function is > displayed. > > >> >> That's a judgement call. Just do what you think is best. > > Meh. Lets decide what the format should be. Since no one has cared so far, > maybe just leave it as is, and all future additions follows the same pattern. > As such, I’m creating > > doc/reference/api/TSMimeHdrFieldCreate.en.rst >
So, looking at this some more, and talking to myself as usual, the current format does not lean itself well towards documenting large sets of APIs such as the TSMimeHdrField* stuff. What the ‘templates’ seem to do is one section for all functions documenting the prototypes, and then one section documenting the return codes. This will get real ugly fast with 10’s of functions. What I think we need to do, assuming this is how we want to organize the docs, is to have one section introducing the overall purpose of the set of APIs, followed by <n> sections, one for each API, where each section documents the function prototype and return type, as well as the usage. This is how the old PDF documentation was laid out. I have no idea how that translates to Sphinx layout ... Thoughts? — Leif
