You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Leif Hedstrom <zw...@apache.org> on 2013/11/17 01:46:16 UTC
Questions on Sphinx docs
I'm a little confused now, with regards how the API documentation is / should be laid out. I wanted to update the docs for TSMimeHdrFieldValueStringGet(), only to find out that it's not documented any more. It used to be in the original Inktomi PDF docs, but now all I can see is a link to
http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a4aa55cd4eeb9e6d0a5151c02f0c18c28
which I think is the Doxygen output.
Peach told me in IRC to add it to
https://trafficserver.readthedocs.org/en/latest/reference/api/index.en.html
which seems reasonable. However, I have a few questions on this:
Do we create one page / file for every plugin API? Or do we try to group them together by some logic (things logically belonging together, like TSmalloc and TSfree)? If there's a group, what do the file get named, and how do we make the grouping such that we all agree and work on the same grouping?
How does this relate to the docs in docs/sdk, e.g. docs/sdk/mime-headers? Do we add or change links / referencesin docs/sdk over to the reference/api sections?
Do we also have to produce a man page, or is that what reference/api is all about?
Is there an overall big-picture page describing how the docs should be laid out for the SDK / APIs ? There is a fair amount missing here right now, which we can fairly easy (urgh, did I just stick my head out?) copy from the old PDF documentation.
Thanks,
-- Leif
Re: Questions on Sphinx docs
Posted by Leif Hedstrom <zw...@apache.org>.
On Nov 17, 2013, at 1:52 PM, Leif Hedstrom <zw...@apache.org> wrote:
> 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.
From the IRC discussion, the above does not fit within the man-page structure. Instead, I’d like to suggest that we group APIs with similar functionality, and very similar prototypes and return value semantics in each Sphinx file. For my example, I’m now back to creating one file named TSMimeHdrFieldValueStringGet.en.rst, with the following APIs documented in it:
.. function:: const char* TSMimeHdrFieldValueStringGet(TSMBuffer bufp, ...
.. function:: int TSMimeHdrFieldValueIntGet(TSMBuffer bufp, ...
.. function:: int64_t TSMimeHdrFieldValueInt64Get(TSMBuffer bufp, ...
.. function:: unsigned int TSMimeHdrFieldValueUintGet(TSMBuffer bufp, ...
.. function:: time_t TSMimeHdrFieldValueDateGet(TSMBuffer bufp, …
Set() functions, object creations etc. will have to go in separate docs (IMO at least).
Most of the pages we have already falls within that guideline, but a few of them probably ought to get broken up into 2 or more files. E.g. TSUrlCreate.en.rst would be split up into one for “creation” of URLs (Create, Clone, Parse etc.), one for Set() methods and one for Get() methods.
More thoughts ?
— Leif
Re: Questions on Sphinx docs
Posted by Leif Hedstrom <zw...@apache.org>.
On Nov 17, 2013, at 1:43 PM, Leif Hedstrom <zw...@apache.org> 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
Re: Questions on Sphinx docs
Posted by Leif Hedstrom <zw...@apache.org>.
On Nov 16, 2013, at 8:42 PM, James Peach <jp...@apache.org> wrote:
>
> Choose what you think the most sensible name is. For real man pages, we could link them by all the names, but that's probably tricky with Sphinx.
It looks like we’re now creating them with whatever function “creates” an entity of the grouping, so maybe we stick with that. I don’t care strongly, other than (as usual) I think it needs to be consistent.
>
>
> Reference docs are for reference. The SDK docs are for exposition and tutorial material.
Ok, makes sense, what’s real confusing right now is that they link to the Doxygen docs on people.apache.org/~amc/.
>
>
> 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
which is slightly confusing, since the file for now only contains the docs for TSMimeHdrFieldValueStringGet :).
Cheers,
— Leif
Re: Questions on Sphinx docs
Posted by James Peach <jp...@apache.org>.
On Nov 16, 2013, at 6:30 PM, Leif Hedstrom <zw...@apache.org> wrote:
>
> On Nov 16, 2013, at 5:46 PM, Leif Hedstrom <zw...@apache.org> wrote:
>
>>
>>
>> which seems reasonable. However, I have a few questions on this:
>
> Bah, email ate my formatting. This is how I wanted the questions to look:
>
> * Do we create one page / file for every plugin API? Or do we try to group them together by some logic (things logically belonging together, like TSmalloc and TSfree)?
We group them, otherwise there would be too much boiler plate and man pages would proliferate like bunnies.
> If there's a group, what do the file get named,
Choose what you think the most sensible name is. For real man pages, we could link them by all the names, but that's probably tricky with Sphinx.
> and how do we make the grouping such that we all agree and work on the same grouping?
I used my judgement and no-one has complained yet.
>
> * How does this relate to the docs in docs/sdk, e.g. docs/sdk/mime-headers? Do we add or change links / referencesin docs/sdk over to the reference/api sections?
Reference docs are for reference. The SDK docs are for exposition and tutorial material.
>
> * Do we also have to produce a man page, or is that what reference/api is all about?
Everything in reference/ produces a man page.
> Poking around some more, I see several pages which does the grouping. As such, I'm wondering if e.g. TSUrlCreate.en.rst should be renamed to just TSUrl.en.rst ? And if that's the case, we ought to put all TSMimeHdrField* APIs into one page, TSMimeHdrField.en.rst ?
That's a judgement call. Just do what you think is best.
> Looking at the list, the natural grouping / renaming (of what we have) would be
>
> TSHttpParser
> TSHttpTxnMilestone
> TSIOBuffer
> TSMBuffer
> TSPlugin
> TSRemap
> TSUrl
>
> Other sections would probably look nicer with a more generic / descriptive title, e.g. "Debugging", "Hooks", "Remap Plugins", "Life Cycles" etc. But then maybe the above ought to be renamed too, e.g. "HTTP Parser", "Milestone metrics" and other descriptive names.
These are section 3 man pages, so name them after the "root" API. Typing "man HTTP\ Parser" is not going to work well.
J
Re: Questions on Sphinx docs
Posted by Leif Hedstrom <zw...@apache.org>.
On Nov 16, 2013, at 5:46 PM, Leif Hedstrom <zw...@apache.org> wrote:
>
>
> which seems reasonable. However, I have a few questions on this:
Bah, email ate my formatting. This is how I wanted the questions to look:
* Do we create one page / file for every plugin API? Or do we try to group them together by some logic (things logically belonging together, like TSmalloc and TSfree)? If there's a group, what do the file get named, and how do we make the grouping such that we all agree and work on the same grouping?
* How does this relate to the docs in docs/sdk, e.g. docs/sdk/mime-headers? Do we add or change links / referencesin docs/sdk over to the reference/api sections?
* Do we also have to produce a man page, or is that what reference/api is all about?
Poking around some more, I see several pages which does the grouping. As such, I'm wondering if e.g. TSUrlCreate.en.rst should be renamed to just TSUrl.en.rst ? And if that's the case, we ought to put all TSMimeHdrField* APIs into one page, TSMimeHdrField.en.rst ?
Looking at the list, the natural grouping / renaming (of what we have) would be
TSHttpParser
TSHttpTxnMilestone
TSIOBuffer
TSMBuffer
TSPlugin
TSRemap
TSUrl
Other sections would probably look nicer with a more generic / descriptive title, e.g. "Debugging", "Hooks", "Remap Plugins", "Life Cycles" etc. But then maybe the above ought to be renamed too, e.g. "HTTP Parser", "Milestone metrics" and other descriptive names.
Thoughts?
-- Leif