Include Titles in FileItems

README.md

@@ -414,7 +414,8 @@ documents:
       numbered: true
       reversed: false
       items:
-      - doc1
+      - path: doc1
+        title: null
       titlesonly: true
     title: null
 meta: {}

sphinx_external_toc/api.py

@@ -17,13 +17,20 @@
 URL_PATTERN: str = r".+://.*"
 
 
-class FileItem(str):
+@dataclass(**DC_SLOTS)
+class FileItem:
     """A document path in a toctree list.
 
     This should be in POSIX format (folders split by ``/``), relative to the
     source directory, and can be with or without an extension.
     """
 
+    path: str = field(validator=[instance_of(str)])
+    title: Optional[str] = field(default=None, validator=optional(instance_of(str)))
+
+    def __post_init__(self):
+        validate_fields(self)
+
 
 class GlobItem(str):
     """A document glob in a toctree list."""

sphinx_external_toc/events.py

@@ -251,10 +251,8 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
                 subnode["entries"].append((entry.title, entry.url))
 
             elif isinstance(entry, FileItem):
-
-                child_doc_item = site_map[entry]
-                docname = str(entry)
-                title = child_doc_item.title
+                docname = entry.path
+                title = entry.title
 
                 docname = remove_suffix(docname, app.config.source_suffix)
 

sphinx_external_toc/parsing.py

@@ -238,7 +238,7 @@ def _parse_doc_item(
 
             try:
                 if link_keys == {FILE_KEY}:
-                    items.append(FileItem(item_data[FILE_KEY]))
+                    items.append(FileItem(item_data[FILE_KEY], item_data.get("title")))
                 elif link_keys == {GLOB_KEY}:
                     items.append(GlobItem(item_data[GLOB_KEY]))
                 elif link_keys == {URL_KEY}:
@@ -403,16 +403,16 @@ def _docitem_to_dict(
 
     def _parse_item(item):
         if isinstance(item, FileItem):
-            if item in site_map:
+            if item.path in site_map:
                 return _docitem_to_dict(
-                    site_map[item],
+                    site_map[item.path],
                     site_map,
                     depth=depth + 1,
                     file_format=file_format,
                     skip_defaults=skip_defaults,
                     parsed_docnames=parsed_docnames,
                 )
-            return {FILE_KEY: str(item)}
+            return {FILE_KEY: item.path}
         if isinstance(item, GlobItem):
             return {GLOB_KEY: str(item)}
         if isinstance(item, UrlItem):

tests/_toc_files/basic.yml

@@ -6,6 +6,7 @@ subtrees:
     numbered: true
     entries:
     - file: doc1
+      title: "custom"
     - file: doc2
     - file: doc3
       subtrees:

tests/test_parsing/test_create_toc_dict_basic_.yml

@@ -1,5 +1,6 @@
 entries:
 - file: doc1
+  title: custom
 - file: doc2
 - entries:
   - file: subfolder/doc4

tests/test_parsing/test_file_to_sitemap_basic_.yml

@@ -2,7 +2,7 @@ documents:
   doc1:
     docname: doc1
     subtrees: []
-    title: null
+    title: custom
   doc2:
     docname: doc2
     subtrees: []
@@ -13,7 +13,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - subfolder/doc4
+      - path: subfolder/doc4
+        title: null
       - title: null
         url: https://example.com
       maxdepth: -1
@@ -27,9 +28,12 @@ documents:
     - caption: Part Caption
       hidden: true
       items:
-      - doc1
-      - doc2
-      - doc3
+      - path: doc1
+        title: custom
+      - path: doc2
+        title: null
+      - path: doc3
+        title: null
       maxdepth: -1
       numbered: true
       reversed: false

tests/test_parsing/test_file_to_sitemap_basic_compressed_.yml

@@ -13,7 +13,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - doc4
+      - path: doc4
+        title: null
       - title: null
         url: https://example.com
       maxdepth: -1
@@ -31,9 +32,12 @@ documents:
     - caption: null
       hidden: true
       items:
-      - doc1
-      - doc2
-      - doc3
+      - path: doc1
+        title: null
+      - path: doc2
+        title: null
+      - path: doc3
+        title: null
       maxdepth: -1
       numbered: true
       reversed: false

tests/test_parsing/test_file_to_sitemap_exclude_missing_.yml

@@ -9,7 +9,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - doc1
+      - path: doc1
+        title: null
       - subfolder/other*
       maxdepth: -1
       numbered: false

tests/test_parsing/test_file_to_sitemap_nested_.yml

@@ -13,7 +13,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - folder/subfolder/doc4
+      - path: folder/subfolder/doc4
+        title: null
       - folder/globfolder/*
       maxdepth: -1
       numbered: false
@@ -30,9 +31,12 @@ documents:
     - caption: null
       hidden: true
       items:
-      - folder/doc1
-      - folder/doc2
-      - folder/doc3
+      - path: folder/doc1
+        title: null
+      - path: folder/doc2
+        title: null
+      - path: folder/doc3
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false

tests/test_parsing/test_file_to_sitemap_tableofcontents_.yml

@@ -13,15 +13,17 @@ documents:
     - caption: null
       hidden: true
       items:
-      - doc1
+      - path: doc1
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false
       titlesonly: false
     - caption: null
       hidden: true
       items:
-      - doc2
+      - path: doc2
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false

tests/test_sphinx/test_success_basic_.xml

@@ -3,4 +3,4 @@
         <title>
             Heading: intro.rst
         <compound classes="toctree-wrapper">
-            <toctree caption="Part Caption" entries="(None,\ 'doc1') (None,\ 'doc2') (None,\ 'doc3')" glob="False" hidden="True" includefiles="doc1 doc2 doc3" includehidden="False" maxdepth="-1" numbered="999" parent="intro" rawcaption="Part Caption" titlesonly="True">
+            <toctree caption="Part Caption" entries="('custom',\ 'doc1') (None,\ 'doc2') (None,\ 'doc3')" glob="False" hidden="True" includefiles="doc1 doc2 doc3" includehidden="False" maxdepth="-1" numbered="999" parent="intro" rawcaption="Part Caption" titlesonly="True">

tests/test_tools/test_create_site_map_from_path.yml

@@ -13,12 +13,18 @@ documents:
     - caption: null
       hidden: true
       items:
-      - 1_other
-      - 11_other
-      - subfolder1/index
-      - subfolder2/index
-      - subfolder3/no_index1
-      - subfolder14/index
+      - path: 1_other
+        title: null
+      - path: 11_other
+        title: null
+      - path: subfolder1/index
+        title: null
+      - path: subfolder2/index
+        title: null
+      - path: subfolder3/no_index1
+        title: null
+      - path: subfolder14/index
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false
@@ -34,7 +40,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - subfolder14/subsubfolder/index
+      - path: subfolder14/subsubfolder/index
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false
@@ -46,7 +53,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - subfolder14/subsubfolder/other
+      - path: subfolder14/subsubfolder/other
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false
@@ -62,7 +70,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - subfolder2/other
+      - path: subfolder2/other
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false
@@ -78,7 +87,8 @@ documents:
     - caption: null
       hidden: true
       items:
-      - subfolder3/no_index2
+      - path: subfolder3/no_index2
+        title: null
       maxdepth: -1
       numbered: false
       reversed: false