From d1a0cd20cac32644a93621f6ccf8794427f0389b Mon Sep 17 00:00:00 2001 From: bame-da Date: Wed, 25 Jan 2023 09:45:07 +0100 Subject: [PATCH 1/7] Include Titles in FileItems --- sphinx_external_toc/api.py | 10 +++++++--- sphinx_external_toc/events.py | 6 ++---- sphinx_external_toc/parsing.py | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/sphinx_external_toc/api.py b/sphinx_external_toc/api.py index 3bd8155..41376df 100644 --- a/sphinx_external_toc/api.py +++ b/sphinx_external_toc/api.py @@ -16,14 +16,18 @@ #: Pattern used to match URL items. 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..d28d7f3 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}: From adf2b6f1e4c4b51856a33e06629748ada3a6721d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 25 Jan 2023 09:01:19 +0000 Subject: [PATCH 2/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- sphinx_external_toc/api.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/sphinx_external_toc/api.py b/sphinx_external_toc/api.py index 41376df..f7065db 100644 --- a/sphinx_external_toc/api.py +++ b/sphinx_external_toc/api.py @@ -16,6 +16,7 @@ #: Pattern used to match URL items. URL_PATTERN: str = r".+://.*" + @dataclass(**DC_SLOTS) class FileItem: """A document path in a toctree list. @@ -23,12 +24,14 @@ class FileItem: 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.""" From 7e6504676498aa87d715fd4ff3190349bbd3def0 Mon Sep 17 00:00:00 2001 From: bame-da Date: Wed, 25 Jan 2023 11:01:09 +0100 Subject: [PATCH 3/7] Fix tests --- README.md | 3 +- sphinx_external_toc/parsing.py | 7 +++-- sphinx_external_toc/tools.py | 1 + .../test_file_to_sitemap_basic_.yml | 12 +++++--- ...test_file_to_sitemap_basic_compressed_.yml | 12 +++++--- .../test_file_to_sitemap_exclude_missing_.yml | 3 +- .../test_file_to_sitemap_nested_.yml | 12 +++++--- .../test_file_to_sitemap_tableofcontents_.yml | 6 ++-- .../test_create_site_map_from_path.yml | 30 ++++++++++++------- 9 files changed, 57 insertions(+), 29 deletions(-) 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/parsing.py b/sphinx_external_toc/parsing.py index d28d7f3..4e682d9 100644 --- a/sphinx_external_toc/parsing.py +++ b/sphinx_external_toc/parsing.py @@ -3,6 +3,7 @@ from dataclasses import dataclass, fields from pathlib import Path from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Union +import logging import yaml @@ -403,16 +404,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/sphinx_external_toc/tools.py b/sphinx_external_toc/tools.py index 0d77ae6..35819f1 100644 --- a/sphinx_external_toc/tools.py +++ b/sphinx_external_toc/tools.py @@ -4,6 +4,7 @@ from itertools import chain from pathlib import Path, PurePosixPath from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union +import logging import yaml diff --git a/tests/test_parsing/test_file_to_sitemap_basic_.yml b/tests/test_parsing/test_file_to_sitemap_basic_.yml index 38a03fc..ed954b7 100644 --- a/tests/test_parsing/test_file_to_sitemap_basic_.yml +++ b/tests/test_parsing/test_file_to_sitemap_basic_.yml @@ -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: 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_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_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 From 176d6d4f00a52b849cab6d1c5ea8a9211764089f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 25 Jan 2023 10:01:48 +0000 Subject: [PATCH 4/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- sphinx_external_toc/parsing.py | 2 +- sphinx_external_toc/tools.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx_external_toc/parsing.py b/sphinx_external_toc/parsing.py index 4e682d9..6759d1c 100644 --- a/sphinx_external_toc/parsing.py +++ b/sphinx_external_toc/parsing.py @@ -1,9 +1,9 @@ """Parse the ToC to a `SiteMap` object.""" +import logging from collections.abc import Mapping from dataclasses import dataclass, fields from pathlib import Path from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Union -import logging import yaml diff --git a/sphinx_external_toc/tools.py b/sphinx_external_toc/tools.py index 35819f1..af448c3 100644 --- a/sphinx_external_toc/tools.py +++ b/sphinx_external_toc/tools.py @@ -1,10 +1,10 @@ +import logging import re import shutil from fnmatch import fnmatch from itertools import chain from pathlib import Path, PurePosixPath from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union -import logging import yaml From 7675da6f4bb7b6d678860cfa076d25fec552945f Mon Sep 17 00:00:00 2001 From: bame-da Date: Wed, 25 Jan 2023 11:02:52 +0100 Subject: [PATCH 5/7] Revert unnecessary import --- sphinx_external_toc/tools.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sphinx_external_toc/tools.py b/sphinx_external_toc/tools.py index af448c3..0d77ae6 100644 --- a/sphinx_external_toc/tools.py +++ b/sphinx_external_toc/tools.py @@ -1,4 +1,3 @@ -import logging import re import shutil from fnmatch import fnmatch From 5be981d69c7a574ce5586adbc414d1f368af3b28 Mon Sep 17 00:00:00 2001 From: bame-da Date: Wed, 25 Jan 2023 11:05:01 +0100 Subject: [PATCH 6/7] Revert another unnecessary import --- sphinx_external_toc/parsing.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sphinx_external_toc/parsing.py b/sphinx_external_toc/parsing.py index 6759d1c..ae97480 100644 --- a/sphinx_external_toc/parsing.py +++ b/sphinx_external_toc/parsing.py @@ -1,5 +1,4 @@ """Parse the ToC to a `SiteMap` object.""" -import logging from collections.abc import Mapping from dataclasses import dataclass, fields from pathlib import Path From 8a33082711c7ccf3472a9381f9c9eee474f71a2d Mon Sep 17 00:00:00 2001 From: bame-da Date: Wed, 25 Jan 2023 11:11:26 +0100 Subject: [PATCH 7/7] Add test case for titles --- tests/_toc_files/basic.yml | 1 + tests/test_parsing/test_create_toc_dict_basic_.yml | 1 + tests/test_parsing/test_file_to_sitemap_basic_.yml | 4 ++-- tests/test_sphinx/test_success_basic_.xml | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) 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 ed954b7..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: [] @@ -29,7 +29,7 @@ documents: hidden: true items: - path: doc1 - title: null + title: custom - path: doc2 title: null - path: doc3 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">