Index based on fields of a directive; where to start?

[Viktor Haag]

I'm using a slightly modified version of the HTTP Domain third party extension to handle API reference docs for a REST-like web services API.

The domain does build a separate index of its own that collects together all the API URL "routes", organized by HTTP method. That's all fine and good.

However, I'd like to add a new index that collates together routes based on information contained in the fields of the various API calls.

For example, suppose I have a whole bunch of HTTP GET calls on collections that all allow a caller to pass a query parameter called "AddedSince" (carrying a date-time string value) so that the caller gets back only the items added to the collection since their provided time, something like this:

.. http:get:: /api/users/

   Retrieve list of known users.

   :query AddedSince: Return only users added since this time.

   :qtype AddedSince: ISO8601 date-time string

Suppose I wanted an index page that would collect together all the URL paths that offered this query parameter? I'm at a bit of a loss to know how to dive into a directive's options... can anyone point me at examples that might get me further down the road on this?

Thanks,

--

Viktor 

[Viktor Haag]

Some more looking at code carefully leads me to want to rephrase my question to be a bit more precise (with wording that's more aligned with what things are actually called in the Sphinx code):

So, I have a directive, which can have options. The directive also supports inclusion of a number of Fields (one of which is "query" from the example above).

What I don't see is a way to have an index built for field names where something of the parent, containing directive node is used as the value for the index entry.

Are there examples in the Sphinx code someone can point me to where a directive's contained field can somehow reach out to find out stuff about its parent containing directive node? (this way I could have the index "key" be "AddedSince", and it's list of associated values be the paths from all HTTP route entries that contain an AddedSince query field....

v.

[Komiya Takeshi]

Hi,

The content body part of your directives is not parsed yet on handle_signature() called.

To handle and index it, you can use Domain#process_doc() handler like following:

class YourHTTPDomain(Domain):
    def process_doc(self, env, fromdocname, document):
        for node in document.traverse(addnodes.desc):
           if node['domain'] == 'http':  # The `node` is generated by directives of httpdomain
               # Add index to self.data here

I did not test this code. but it might work.

Thanks,

Takeshi KOMIYA

2016年10月7日金曜日 4時23分31秒 UTC+9 Viktor Haag:

[Viktor Haag]

Hi Komiya-san,

Thanks very much for the helpful reply; I will look into using this pattern with the httpdomain package I have.

Regards,

--

Viktor Haag

[Konstantin Molchanov]

Hi,Viktor!

Would you mind sharing your code when you have your custom HTTP domain working? Having an index of all routes sounds useful.

[Viktor Haag]

On 15 November 2016 at 08:54, Konstantin Molchanov <moig...@gmail.com> wrote:

Hi,Viktor!

Would you mind sharing your code when you have your custom HTTP domain working? Having an index of all routes sounds useful.

Hi Konstantin -- the domain already does indexing of all the routes, so that's in the package. What I was seeking to add was a way to build up an index of all route attributes of a particular kind.

From my example in this thread, I'd like to collect together all the routes in an index that have a ":query AddedSAince:" field so that I can have a reference table for all APIs that support an 'AddedSince' kind of behaviour. (My real field is something entirely different, but is actually highly domain-specific to my needs and so wouldn't make such a good example as this; the general pattern is the same.)

Cheers,

--

Viktor