diff --git a/README.md b/README.md index 4e4e619..82405e1 100644 --- a/README.md +++ b/README.md @@ -414,7 +414,8 @@ documents: numbered: true reversed: false items: - - doc1 + - path: doc1 + title: null titlesonly: true title: null meta: {} diff --git a/sphinx_external_toc/api.py b/sphinx_external_toc/api.py index 3bd8155..f7065db 100644 --- a/sphinx_external_toc/api.py +++ b/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.""" diff --git a/sphinx_external_toc/events.py b/sphinx_external_toc/events.py index 522b7b8..58b95e2 100644 --- a/sphinx_external_toc/events.py +++ b/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) diff --git a/sphinx_external_toc/parsing.py b/sphinx_external_toc/parsing.py index 8e313a1..ae97480 100644 --- a/sphinx_external_toc/parsing.py +++ b/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): diff --git a/tests/_toc_files/basic.yml b/tests/_toc_files/basic.yml index 712b63c..ad129fb 100644 --- a/tests/_toc_files/basic.yml +++ b/tests/_toc_files/basic.yml @@ -6,6 +6,7 @@ subtrees: numbered: true entries: - file: doc1 + title: "custom" - file: doc2 - file: doc3 subtrees: diff --git a/tests/test_parsing/test_create_toc_dict_basic_.yml b/tests/test_parsing/test_create_toc_dict_basic_.yml index a8414c6..b72e9f2 100644 --- a/tests/test_parsing/test_create_toc_dict_basic_.yml +++ b/tests/test_parsing/test_create_toc_dict_basic_.yml @@ -1,5 +1,6 @@ entries: - file: doc1 + title: custom - file: doc2 - entries: - file: subfolder/doc4 diff --git a/tests/test_parsing/test_file_to_sitemap_basic_.yml b/tests/test_parsing/test_file_to_sitemap_basic_.yml index 38a03fc..6e57542 100644 --- a/tests/test_parsing/test_file_to_sitemap_basic_.yml +++ b/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 diff --git a/tests/test_parsing/test_file_to_sitemap_basic_compressed_.yml b/tests/test_parsing/test_file_to_sitemap_basic_compressed_.yml index 11dd7a6..0460b27 100644 --- a/tests/test_parsing/test_file_to_sitemap_basic_compressed_.yml +++ b/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 diff --git a/tests/test_parsing/test_file_to_sitemap_exclude_missing_.yml b/tests/test_parsing/test_file_to_sitemap_exclude_missing_.yml index b7a3ac2..1d7e213 100644 --- a/tests/test_parsing/test_file_to_sitemap_exclude_missing_.yml +++ b/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 diff --git a/tests/test_parsing/test_file_to_sitemap_nested_.yml b/tests/test_parsing/test_file_to_sitemap_nested_.yml index e18d476..b878dd5 100644 --- a/tests/test_parsing/test_file_to_sitemap_nested_.yml +++ b/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 diff --git a/tests/test_parsing/test_file_to_sitemap_tableofcontents_.yml b/tests/test_parsing/test_file_to_sitemap_tableofcontents_.yml index 1f6d62b..5a3fee5 100644 --- a/tests/test_parsing/test_file_to_sitemap_tableofcontents_.yml +++ b/tests/test_parsing/test_file_to_sitemap_tableofcontents_.yml @@ -13,7 +13,8 @@ documents: - caption: null hidden: true items: - - doc1 + - path: doc1 + title: null maxdepth: -1 numbered: false reversed: false @@ -21,7 +22,8 @@ documents: - caption: null hidden: true items: - - doc2 + - path: doc2 + title: null maxdepth: -1 numbered: false reversed: false diff --git a/tests/test_sphinx/test_success_basic_.xml b/tests/test_sphinx/test_success_basic_.xml index 93fc4ae..f24fde5 100644 --- a/tests/test_sphinx/test_success_basic_.xml +++ b/tests/test_sphinx/test_success_basic_.xml @@ -3,4 +3,4 @@ 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"> diff --git a/tests/test_tools/test_create_site_map_from_path.yml b/tests/test_tools/test_create_site_map_from_path.yml index fccd9ea..34d60c5 100644 --- a/tests/test_tools/test_create_site_map_from_path.yml +++ b/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