From ca605c743709841e3446ac8e8f1a7948f4746b44 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Tue, 16 Apr 2019 22:32:51 +0900
Subject: [PATCH] Add :type: option for rst:directive:option directive

---
 doc/usage/restructuredtext/domains.rst | 14 ++++++++++++++
 sphinx/domains/rst.py                  | 15 +++++++++++++--
 tests/test_domain_rst.py               | 15 +++++++++++++++
 3 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index 8244202aa..0f93c89d4 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/doc/usage/restructuredtext/domains.rst
@@ -1444,6 +1444,20 @@ The reStructuredText domain (name **rst**) provides the following directives:
 
           .. rst:directive:option:: glob
 
+   .. rubric:: options
+
+   .. rst:directive:option:: type
+      :type: description for the option of directive
+
+      Describe the type of option value.
+
+      For example::
+
+         .. rst:directive:: toctree
+
+            .. rst:directive:option:: maxdepth
+               :type: integer or no value
+
    .. versionadded:: 2.1
 
 .. rst:directive:: .. rst:role:: name
diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py
index bd1ab2b28..f054abf28 100644
--- a/sphinx/domains/rst.py
+++ b/sphinx/domains/rst.py
@@ -11,6 +11,8 @@
 import re
 from typing import cast
 
+from docutils.parsers.rst import directives
+
 from sphinx import addnodes
 from sphinx.directives import ObjectDescription
 from sphinx.domains import Domain, ObjType
@@ -115,6 +117,11 @@ class ReSTDirectiveOption(ReSTMarkup):
     """
     Description of an option for reST directive.
     """
+    option_spec = ReSTMarkup.option_spec.copy()
+    option_spec.update({
+        'type': directives.unchanged,
+    })
+
     def handle_signature(self, sig, signode):
         # type: (str, addnodes.desc_signature) -> str
         try:
@@ -125,6 +132,9 @@ class ReSTDirectiveOption(ReSTMarkup):
         signode += addnodes.desc_name(':%s:' % name, ':%s:' % name)
         if argument:
             signode += addnodes.desc_annotation(' ' + argument, ' ' + argument)
+        if self.options.get('type'):
+            text = ' (%s)' % self.options['type']
+            signode += addnodes.desc_annotation(text, text)
         return name
 
     def add_target_and_index(self, name, sig, signode):
@@ -179,8 +189,9 @@ class ReSTDomain(Domain):
     label = 'reStructuredText'
 
     object_types = {
-        'directive': ObjType(_('directive'), 'dir'),
-        'role':      ObjType(_('role'),      'role'),
+        'directive':        ObjType(_('directive'), 'dir'),
+        'directive:option': ObjType(_('directive-option'), 'dir'),
+        'role':             ObjType(_('role'),      'role'),
     }
     directives = {
         'directive': ReSTDirective,
diff --git a/tests/test_domain_rst.py b/tests/test_domain_rst.py
index 5f49206ca..207ff1ff3 100644
--- a/tests/test_domain_rst.py
+++ b/tests/test_domain_rst.py
@@ -95,6 +95,21 @@ def test_rst_directive_option_with_argument(app):
                 domain="rst", objtype="directive:option", noindex=False)
 
 
+def test_rst_directive_option_type(app):
+    text = (".. rst:directive:option:: foo\n"
+            "   :type: directives.flags\n")
+    doctree = restructuredtext.parse(app, text)
+    assert_node(doctree, (addnodes.index,
+                          [desc, ([desc_signature, ([desc_name, ":foo:"],
+                                                    [desc_annotation, " (directives.flags)"])],
+                                  [desc_content, ()])]))
+    assert_node(doctree[0],
+                entries=[("single", ":foo: (directive option)",
+                          "directive:option--foo", "", "F")])
+    assert_node(doctree[1], addnodes.desc, desctype="directive:option",
+                domain="rst", objtype="directive:option", noindex=False)
+
+
 def test_rst_directive_and_directive_option(app):
     text = (".. rst:directive:: foo\n"
             "\n"