From 6e0b5c7b6aed5016fe10ebf1753e0ab2ad08c0c7 Mon Sep 17 00:00:00 2001
From: alephzero <48891271+alephzero@users.noreply.github.com>
Date: Sat, 18 Apr 2020 09:51:07 -0700
Subject: [PATCH 1/2] doc: correct doxygenfile section example

https://github.com/michaeljones/breathe/pull/501
---
 documentation/source/file.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/source/file.rst b/documentation/source/file.rst
index 33837f87..bc5b4268 100644
--- a/documentation/source/file.rst
+++ b/documentation/source/file.rst
@@ -31,7 +31,7 @@ sections, in that order::
 
    .. doxygenfile:: nutshell.h
       :project: nutshell
-      :sections: briefdescription public-type
+      :sections: briefdescription innerclass public-type
 
 It produces this output:
 
@@ -39,7 +39,7 @@ It produces this output:
 
 .. doxygenfile:: nutshell.h
    :project: nutshell
-   :sections: briefdescription public-type
+   :sections: briefdescription innerclass public-type
 
 Example with Nested Namespaces
 ------------------------------

From 297f92d238ec7622cff52963b3bb8785e48c936b Mon Sep 17 00:00:00 2001
From: Melvin Vermeeren <mail@mel.vin>
Date: Sat, 18 Apr 2020 22:22:08 +0200
Subject: [PATCH 2/2] doc: add intro and section type table for
 doxygen(auto)file

---
 breathe/renderer/sphinxrenderer.py |  3 ++
 documentation/source/autofile.rst  |  3 ++
 documentation/source/file.rst      | 64 +++++++++++++++++++++++++++++-
 3 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/breathe/renderer/sphinxrenderer.py b/breathe/renderer/sphinxrenderer.py
index 56ebd932..2513e2e0 100644
--- a/breathe/renderer/sphinxrenderer.py
+++ b/breathe/renderer/sphinxrenderer.py
@@ -544,6 +544,9 @@ def render_signature(file_data, doxygen_target, name, kind):
     # We store both the identified and appropriate title text here as we want to define the order
     # here and the titles for the SectionDefTypeSubRenderer but we don't want the repetition of
     # having two lists in case they fall out of sync
+    #
+    # If this list is edited, also change the sections option documentation for
+    # the doxygen(auto)file directive in documentation/source/autofile.rst.
     sections = [
         ("user-defined", "User Defined"),
         ("public-type", "Public Types"),
diff --git a/documentation/source/autofile.rst b/documentation/source/autofile.rst
index ad30d554..3e37653f 100644
--- a/documentation/source/autofile.rst
+++ b/documentation/source/autofile.rst
@@ -4,6 +4,9 @@
 autodoxygenfile Directive Example
 =================================
 
+For more details and directive documentation please see :ref:`file-example`,
+which is very similar to this directive.
+
 Working Example
 ---------------
 
diff --git a/documentation/source/file.rst b/documentation/source/file.rst
index bc5b4268..9d81ea40 100644
--- a/documentation/source/file.rst
+++ b/documentation/source/file.rst
@@ -1,8 +1,68 @@
 
 .. _file-example:
 
-doxygenfile Directive Example
-=============================
+doxygenfile Directive
+=====================
+
+This directive generates the appropriate output for a single source file. It
+takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
+and additionally the ``sections`` options.
+
+For the standard option refer to the documentation on the main directives page.
+The directive-specific options are documented below.
+
+``sections``
+   Limit the sections to render for the given source file to the given list.
+   Many of the names come from Doxygen and Breathe internals and may not make
+   sense from an external point of view. Nevertheless it is hoped this table is
+   useful.
+
+   .. csv-table:: Section types
+      :header: "Type", "Description"
+
+      "briefdescription", "Brief description"
+      "dcop-func", "DCOP Function"
+      "define", "Define"
+      "derivedcompoundref", "Derived compound reference"
+      "detaileddescription", "Detailed description"
+      "enum", "Enumerator"
+      "event", "Event"
+      "friend", "Friend"
+      "func", "Function"
+      "innerclass", "**Must be given to show sections inside a class**"
+      "innernamespace", "**Must be given to show sections inside a namespace**"
+      "package-attrib", "Package attribute"
+      "package-func", "Package function"
+      "package-static-attrib", "Package static attribute"
+      "package-static-func", "Package static function"
+      "package-type", "Package type"
+      "private-attrib", "Private attribute"
+      "private-func", "Private function"
+      "private-slot", "Private slot"
+      "private-static-attrib", "Private static attribute"
+      "private-static-func", "Private static function"
+      "private-type", "Private type"
+      "property", "Property"
+      "protected-attrib", "Protected attribute"
+      "protected-func", "Protected function"
+      "protected-slot", "Protected slot"
+      "protected-static-attrib", "Protected static attribute"
+      "protected-static-func", "Protected static function"
+      "protected-type", "Protected type"
+      "prototype", "Prototype"
+      "public-attrib", "Public attribute"
+      "public-func", "Public function"
+      "public-slot", "Public slot"
+      "public-static-attrib", "Public static attribute"
+      "public-static-func", "Public static function"
+      "public-type", "Public type"
+      "related", "Related"
+      "signal", "Signal"
+      "typedef", "Type definition"
+      "user-defined", "User defined"
+      "var", "Variable"
+
+.. contents::
 
 Example
 -------