♻️ REFACTOR: key items -> entries (#32)

Author: chrisjsewell

README.md

@@ -43,7 +43,7 @@ The value of the `root` key will be a path to a file, in Unix format (folders sp
 This root file will be set as the [`master_doc`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-master_doc).
 :::
 
-Document files can then have a `subtrees` key - denoting a list of individual toctrees for that document - and in-turn each subtree should have a `items` key - denoting a list of children links, that are one of:
+Document files can then have a `subtrees` key - denoting a list of individual toctrees for that document - and in-turn each subtree should have a `entries` key - denoting a list of children links, that are one of:
 
 - `file`: path to a single document file in Unix format,  with or without the file extension (as for `root`)
 - `glob`: path to one or more document files *via* Unix shell-style wildcards (similar to [`fnmatch`](https://docs.python.org/3/library/fnmatch.html), but single stars don't match slashes.)
@@ -58,13 +58,13 @@ This can proceed recursively to any depth.
 ```yaml
 root: intro
 subtrees:
-- items:
+- entries:
   - file: doc1
     subtrees:
-    - items:
+    - entries:
       - file: doc2
         subtrees:
-        - items:
+        - entries:
           - file: doc3
   - url: https://example.com
   - glob: subfolder/other*
@@ -73,16 +73,16 @@ subtrees:
 This is equivalent to having a single `toctree` directive in `intro`, containing `doc1`,
 and a single `toctree` directive in `doc1`, with the `:glob:` flag and containing `doc2`, `https://example.com` and `subfolder/other*`.
 
-As a shorthand, the `items` key can be at the same level as the `file`, which denotes a document with a single subtree.
+As a shorthand, the `entries` key can be at the same level as the `file`, which denotes a document with a single subtree.
 For example, this file is exactly equivalent to the one above:
 
 ```yaml
 root: intro
-items:
+entries:
 - file: doc1
-  items:
+  entries:
   - file: doc2
-    items:
+    entries:
     - file: doc3
 - url: https://example.com
 - glob: subfolder/other*
@@ -96,7 +96,7 @@ With the `title` key you can set an alternative title for a document. and also f
 ```yaml
 root: intro
 subtrees:
-- items:
+- entries:
   - file: doc1
     title: Document 1 Title
   - url: https://example.com
@@ -115,7 +115,7 @@ Each subtree can be configured with a number of options (see also [sphinx `toctr
   If set to `True`, all sub-trees will also be numbered based on nesting (e.g. with `1.1` or `1.1.1`),
   or if set to an integer then the numbering will only be applied to that depth.
 - `reversed` (boolean): If `True` then the entries in the subtree will be listed in reverse order (default `False`).
-  This can be useful when using `glob` items.
+  This can be useful when using `glob` entries.
 - `titlesonly` (boolean): If `True` then only the first heading in the document will be shown in the ToC, not other headings of the same level (default `False`).
 
 These options can be set at the level of the subtree:
@@ -129,11 +129,11 @@ subtrees:
   numbered: True
   reversed: False
   titlesonly: True
-  items:
+  entries:
   - file: doc1
     subtrees:
     - titlesonly: True
-      items:
+      entries:
       - file: doc2
 ```
 
@@ -148,11 +148,11 @@ options:
   numbered: True
   reversed: False
   titlesonly: True
-items:
+entries:
 - file: doc1
   options:
     titlesonly: True
-  items:
+  entries:
   - file: doc2
 ```
 
@@ -168,9 +168,9 @@ options:
   maxdepth: 1
   numbered: True
   reversed: False
-items:
+entries:
 - file: doc1
-  items:
+  entries:
   - file: doc2
 ```
 
@@ -185,18 +185,18 @@ If you want want this numbering to be continuous, check-out the [sphinx-multitoc
 
 ### Using different key-mappings
 
-For certain use-cases, it is helpful to map the `subtrees`/`items` keys to mirror e.g. an output [LaTeX structure](https://www.overleaf.com/learn/latex/sections_and_chapters).
+For certain use-cases, it is helpful to map the `subtrees`/`entries` keys to mirror e.g. an output [LaTeX structure](https://www.overleaf.com/learn/latex/sections_and_chapters).
 
 The `format` key can be used to provide such mappings (and also initial defaults).
 Currently available:
 
 - `jb-article`:
-  - Maps `items` -> `sections`
+  - Maps `entries` -> `sections`
   - Sets the default of `titlesonly` to `true`
 - `jb-book`:
   - Maps the top-level `subtrees` to `parts`
-  - Maps the top-level `items` to `chapters`
-  - Maps other levels of `items` to `sections`
+  - Maps the top-level `entries` to `chapters`
+  - Maps other levels of `entries` to `sections`
   - Sets the default of `titlesonly` to `true`
 
 For example:
@@ -206,9 +206,9 @@ defaults:
   titlesonly: true
 root: index
 subtrees:
-- items:
+- entries:
   - file: doc1
-    items:
+    entries:
     - file: doc2
 ```
 
@@ -266,6 +266,10 @@ external_toc_exclude_missing = True
 Note that, for performance, files that are in *hidden folders* (e.g. in `.tox` or `.venv`) will not be added to `exclude_patterns` even if they are not specified in the ToC.
 You should exclude these folders explicitly.
 
+:::{important}
+This feature is not currently compatible with [orphan files](https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#metadata).
+:::
+
 ## Command-line
 
 This package comes with the `sphinx-etoc` command-line program, with some additional tools.
@@ -299,7 +303,7 @@ Note, you can also add additional files in `meta`/`create_files` amd append text
 
 ```yaml
 root: intro
-items:
+entries:
 - glob: doc*
 meta:
   create_append:
@@ -354,7 +358,7 @@ will create the ToC:
 ```console
 $ sphinx-etoc from-site path/to/folder -i index -s ".*" -e ".rst" -t
 root: index
-items:
+entries:
 - file: 1_a_title
   title: A title
 - file: 11_another_title
@@ -363,20 +367,20 @@ items:
   title: A subfolder
 - file: 2_another_subfolder/index
   title: Another subfolder
-  items:
+  entries:
   - file: 2_another_subfolder/other
     title: Other
 - file: 3_subfolder/1_no_index
   title: No index
-  items:
+  entries:
   - file: 3_subfolder/2_no_index
     title: No index
 - file: 14_subfolder/index
   title: Subfolder
-  items:
+  entries:
   - file: 14_subfolder/subsubfolder/index
     title: Subsubfolder
-    items:
+    entries:
     - file: 14_subfolder/subsubfolder/other
       title: Other
 ```

docs/_toc.yml

@@ -4,14 +4,14 @@ defaults:
 subtrees:
 - caption: Part 1
   numbered: true
-  items:
+  entries:
   - file: doc1
   - file: doc2
-    items:
+    entries:
     - file: subfolder/doc3
     - url: https://example.com
       title: Example Link
 - caption: Part 2
   numbered: true
-  items:
+  entries:
   - glob: subglobs/glob*

docs/toc_tree.pptx

@@ -9,7 +9,7 @@
 from .api import Document, FileItem, GlobItem, SiteMap, TocTree, UrlItem
 
 DEFAULT_SUBTREES_KEY = "subtrees"
-DEFAULT_ITEMS_KEY = "items"
+DEFAULT_ITEMS_KEY = "entries"
 FILE_FORMAT_KEY = "format"
 ROOT_KEY = "root"
 FILE_KEY = "file"
@@ -173,7 +173,7 @@ def _parse_doc_item(
 
         if not (isinstance(toc_data, Mapping) and items_key in toc_data):
             raise MalformedError(
-                f"item not a mapping containing '{items_key}' key @ '{toc_path}'"
+                f"entry not a mapping containing '{items_key}' key @ '{toc_path}'"
             )
 
         items_data = toc_data[items_key]
@@ -187,27 +187,27 @@ def _parse_doc_item(
 
             if not isinstance(item_data, Mapping):
                 raise MalformedError(
-                    f"item not a mapping type @ '{toc_path}{items_key}/{item_idx}'"
+                    f"entry not a mapping type @ '{toc_path}{items_key}/{item_idx}'"
                 )
 
             link_keys = _known_link_keys.intersection(item_data)
 
             # validation checks
             if not link_keys:
                 raise MalformedError(
-                    f"item does not contain one of "
+                    f"entry does not contain one of "
                     f"{_known_link_keys!r} @ '{toc_path}{items_key}/{item_idx}'"
                 )
             if not len(link_keys) == 1:
                 raise MalformedError(
-                    f"item contains incompatible keys "
+                    f"entry contains incompatible keys "
                     f"{link_keys!r} @ '{toc_path}{items_key}/{item_idx}'"
                 )
             for item_key in (GLOB_KEY, URL_KEY):
                 for other_key in (subtrees_key, items_key):
                     if link_keys == {item_key} and other_key in item_data:
                         raise MalformedError(
-                            f"item contains incompatible keys "
+                            f"entry contains incompatible keys "
                             f"'{item_key}' and '{other_key}' @ '{toc_path}{items_key}/{item_idx}'"
                         )
 
@@ -221,7 +221,7 @@ def _parse_doc_item(
             except (ValueError, TypeError) as exc:
                 exc_arg = exc.args[0] if exc.args else ""
                 raise MalformedError(
-                    f"item validation @ '{toc_path}{items_key}/{item_idx}': {exc_arg}"
+                    f"entry validation @ '{toc_path}{items_key}/{item_idx}': {exc_arg}"
                 ) from exc
 
         # generate toc key-word arguments

sphinx_external_toc/parsing.py

@@ -1,5 +1,5 @@
 root: intro
 options:
   titlesonly: 2
-items:
+entries:
 - file: doc1

tests/_bad_toc_files/bad_option_value.yml

@@ -1,3 +1,3 @@
 root: index
-items:
+entries:
 - url: example.com

tests/_bad_toc_files/bad_url.yml

@@ -1,2 +1,2 @@
 root: index
-items: []
+entries: []

tests/_bad_toc_files/empty_items.yml

@@ -1,4 +1,4 @@
 root: index
-items:
+entries:
 - file: doc
   glob: doc*

tests/_bad_toc_files/file_and_glob_present.yml

@@ -1,5 +1,5 @@
 root: index
-items:
+entries:
 - glob: doc*
-  items:
+  entries:
   - file: other

tests/_bad_toc_files/items_in_glob.yml

@@ -1,5 +1,5 @@
 root: index
-items:
+entries:
 - url: http://example.com
-  items:
+  entries:
   - file: other

tests/_bad_toc_files/items_in_url.yml

@@ -1,7 +1,7 @@
 root: main
 subtrees:
 - file: doc1
-  items:
+  entries:
   - file: doc2
   - file: doc3
     unknown: 1

tests/_bad_toc_files/unknown_keys_nested.yml

@@ -4,12 +4,12 @@ root: intro
 subtrees:
   - caption: Part Caption
     numbered: true
-    items:
+    entries:
     - file: doc1
     - file: doc2
     - file: doc3
       subtrees:
-      - items:
+      - entries:
         - file: subfolder/doc4
         - url: https://example.com
 meta:

tests/_toc_files/basic.yml

@@ -3,11 +3,11 @@ defaults:
 options:
   numbered: true
 root: intro
-items:
+entries:
 - file: doc1
 - file: doc2
 - file: doc3
-  items:
+  entries:
   - file: doc4
   - url: https://example.com
 meta:

tests/_toc_files/basic_compressed.yml

@@ -1,5 +1,5 @@
 root: intro
-items:
+entries:
 - file: doc1
 - glob: subfolder/other*
 meta:

tests/_toc_files/exclude_missing.yml

@@ -1,5 +1,5 @@
 root: intro
-items:
+entries:
 - glob: doc*
 meta:
   create_files:

tests/_toc_files/glob.yml

@@ -1,9 +1,9 @@
 root: intro
-items:
+entries:
 - file: folder/doc1
 - file: folder/doc2
 - file: folder/doc3
-  items:
+  entries:
   - file: folder/subfolder/doc4
   - glob: folder/globfolder/*
 meta:

tests/_toc_files/nested.yml

@@ -1,8 +1,8 @@
 root: intro
 subtrees:
-- items:
+- entries:
   - file: doc1
-- items:
+- entries:
   - file: doc2
 meta:
   create_append:

tests/_toc_files/tableofcontents.yml

@@ -1,5 +1,5 @@
 root: intro
-items:
+entries:
 - file: doc1
 meta:
   create_append:

tests/_warning_toc_files/multiple_tableofcontents.yml

@@ -1,5 +1,5 @@
 root: intro
-items:
+entries:
 - glob: doc*
 meta:
   expected_warning: toctree glob pattern