Add HTTP resources to TOC (#80)

* Add HTTP resources to TOC

* Add option to directive and update docs

* Update changelog

* Update changelog

Author: sevdog

CHANGELOG.rst

@@ -22,6 +22,7 @@ Major changes
 - Added support for Python 3.10 up to 3.14.[:pull:`85` by @stevepiercy]
 - Adjusted a unit test regular expression for :file:`bottle_test.py`. [:pull:`85` by @stevepiercy]
 - Use MDN documentation for information about HTTP status codes instead of ``w3.org``. [:pull:`78` by @jamesrobson-secondmind]
+- Added ``:addtoc:`` option for ``http`` directives to register HTTP API endpoints and display them in the page-level table of contents. [:pull:`80` by @sevdog]
 
 
 Internal

docs/index.rst

@@ -313,6 +313,15 @@ Additionally, you may specify custom options to the directives:
       .. http:get:: /users/(int:user_id)/posts/(tag)
          :synopsis: Returns posts by the specified tag for the user
 
+``addtoc``
+   Adds HTTP API endpoint elements to the page-level table of contents.
+
+   .. sourcecode:: rst
+
+      .. http:get:: /users/(int:user_id)/posts/(tag)
+         :addtoc:
+
+   .. versionadded:: 2.0.0
 
 .. _resource-fields:
 

src/sphinxcontrib/httpdomain/__init__.py

@@ -305,6 +305,7 @@ class HTTPResource(ObjectDescription):
     option_spec = {
         'deprecated': directives.flag,
         'noindex': directives.flag,
+        'addtoc': directives.flag,
         'synopsis': lambda x: x,
     }
 
@@ -351,6 +352,25 @@ def add_target_and_index(self, name_cls, sig, signode):
     def get_index_text(self, modname, name):
         return ''
 
+    def _object_hierarchy_parts(self, sig_node):
+        if 'addtoc' in self.options:
+            if 'fullname' not in sig_node:
+                return ()
+            path = sig_node.get('path')
+            method = sig_node.get('method')
+            if not path or not sig_node:
+                return ()
+            return tuple(path.split('/')) + (method, sig_node['fullname'])
+        return ()
+
+    def _toc_entry_name(self, sig_node):
+        if 'addtoc' in self.options:
+            if not sig_node.get('_toc_parts'):
+                return ''
+
+            return sig_node['_toc_parts'][-1]
+        return ''
+
 
 class HTTPOptions(HTTPResource):
 

test/index.rst

@@ -79,6 +79,9 @@ Options
    :deprecated:
    :synopsis: Something special, but use PUT instead
 
+.. http:options:: /baz
+   :addtoc:
+
 Roles
 ~~~~~