♻️ REFACTOR: doc key -> file (#7)

chrisjsewell · web-flow · commit f00220b1be9d · 2021-04-04T20:15:12.000+02:00
diff --git a/README.md b/README.md
@@ -25,50 +25,50 @@ external_toc_path = "_toc.yml"  # optional
 
 ### Basic Structure
 
-A minimal ToC defines the top level `main` key, and a single root document page:
+A minimal ToC defines the top level `main` key, and a single root document file:
 
 ```yaml
 main:
-  doc: intro
+  file: intro
 ```
 
-The value of the `doc` key will be a path to a file (relative to the `conf.py`) with or without the file extension.
+The value of the `file` key will be a path to a file (relative to the `conf.py`) with or without the file extension.
 
 ```{important}
-Each document can only occur once in the ToC!
+Each document file can only occur once in the ToC!
 ```
 
-Document pages can then have a `parts` key - denoting a list of individual toctrees for that document - and in-turn each part should have a `sections` key - denoting a list of children links, that are one of: `doc`, `url` or `glob`:
+Document files can then have a `parts` key - denoting a list of individual toctrees for that document - and in-turn each part should have a `sections` key - denoting a list of children links, that are one of: `file`, `url` or `glob`:
 
-- `doc`: relating to a single document page (as above)
-- `glob`: relating to one or more document pages *via* Unix shell-style wildcards (similar to [`fnmatch`](https://docs.python.org/3/library/fnmatch.html), but single stars don't match slashes.)
-- `url`: relating to an external URL (`http` or `https`)
+- `file`: relating to a single document file
+- `glob`: relating 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.)
+- `url`: relating to an external URL (e.g. `http` or `https`)
 
 This can proceed recursively to any depth.
 
 ```yaml
 main:
-  doc: intro
+  file: intro
   parts:
   - sections:
-    - doc: doc1
+    - file: doc1
       parts:
       - sections:
-        - doc: doc2
+        - file: doc2
         - url: https://example.com
         - glob: other*
 ```
 
-As a shorthand, the `sections` key can be at the same level as the `doc`, which denotes a document with a single `part`.
+As a shorthand, the `sections` key can be at the same level as the `file`, which denotes a document with a single `part`.
 For example, this file is exactly equivalent to the one above:
 
 ```yaml
 main:
-  doc: intro
+  file: intro
   sections:
-  - doc: doc1
+  - file: doc1
     sections:
-    - doc: doc2
+    - file: doc2
     - url: https://example.com
     - glob: other*
 ```
@@ -81,12 +81,12 @@ Each part can also have a `caption`, e.g. for use in ToC side-bars:
 
 ```yaml
 main:
-  doc: intro
+  file: intro
   title: Introduction
   parts:
   - caption: Part Caption
     sections:
-    - doc: doc1
+    - file: doc1
     - url: https://example.com
       title: Example Site
 ```
@@ -97,12 +97,12 @@ You can automatically add numbers to all docs with a part by adding the `numbere
 
 ```yaml
 main:
-  doc: intro
+  file: intro
   parts:
   - numbered: true
     sections:
-    - doc: doc1
-    - doc: doc2
+    - file: doc1
+    - file: doc2
 ```
 
 You can also **limit the TOC numbering depth** by setting the `numbered` flag to an integer instead of `true`, e.g., `numbered: 3`.
@@ -115,16 +115,46 @@ To have e.g. `numbered` added to all toctrees, set it in under a `defaults` top-
 defaults:
   numbered: true
 main:
-  doc: intro
+  file: intro
   sections:
-  - doc: doc1
+  - file: doc1
     sections:
-    - doc: doc2
+    - file: doc2
     - url: https://example.com
 ```
 
 Available keys: `numbered`, `titlesonly`, `reversed`
 
+## Command-line
+
+This package comes with the `sphinx-etoc` command-line program, with some additional tools.
+
+To see all options:
+
+```console
+$ sphinx-etoc --help
+```
+
+To build a template site from only a ToC file:
+
+```console
+$ sphinx-etoc create-site -p path/to/site -e rst path/to/_toc.yml
+```
+
+Note, when using `glob` you can also add additional files in `meta`/`create_additional`, e.g.
+
+```yaml
+main:
+  file: intro
+  sections:
+  - glob: doc*
+meta:
+  create_additional:
+  - doc1
+  - doc2
+  - doc3
+```
+
 ## API
 
 The ToC file is parsed to a `SiteMap`, which is a `MutableMapping` subclass, with keys representing docnames mapping to a `DocItem` that stores information on the toctrees it should contain:
@@ -157,36 +187,6 @@ intro:
   title: Introduction
 ```
 
-## Command-line
-
-This package comes with the `sphinx-etoc` command-line program, with some additional tools.
-
-To see all options:
-
-```console
-$ sphinx-etoc --help
-```
-
-To build a template site from only a ToC file:
-
-```console
-$ sphinx-etoc create-site -p path/to/site -e rst path/to/_toc.yml
-```
-
-Note, when using `glob` you can also add additional files in `meta`/`create_additional`, e.g.
-
-```yaml
-main:
-  doc: intro
-  sections:
-  - glob: doc*
-meta:
-  create_additional:
-  - doc1
-  - doc2
-  - doc3
-```
-
 ## Development Notes
 
 Want to have a built-in CLI including commands:
diff --git a/codecov.yml b/codecov.yml
@@ -2,9 +2,9 @@ coverage:
   status:
     project:
       default:
-        target: 80%
+        target: 82%
         threshold: 0.2%
     patch:
       default:
-        target: 80%
+        target: 75%
         threshold: 0.2%
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -1,19 +1,13 @@
 defaults:
-  # numbered: true
+  numbered: 3
   titlesonly: false
 main:
-  doc: intro
+  file: intro
   title: Introduction
   sections:
-  - doc: doc1
-  - doc: doc2
-    # sections:
-    # - doc: subfolder/doc3
-    # - url: https://example.com
-    #   title: Example Link
-    parts:
-    - numbered: true
-      sections:
-      - doc: subfolder/doc3
-      - url: https://example.com
-        title: Example Link
+  - file: doc1
+  - file: doc2
+    sections:
+    - file: subfolder/doc3
+    - url: https://example.com
+      title: Example Link
diff --git a/sphinx_external_toc/api.py b/sphinx_external_toc/api.py
@@ -154,8 +154,8 @@ def _parse_doc_item(
     data: Dict[str, Any], defaults: Dict[str, Any], path: str
 ) -> Tuple[DocItem, Sequence[Dict[str, Any]]]:
     """Parse a single doc item."""
-    if "doc" not in data:
-        raise MalformedError(f"'doc' key not found: '{path}'")
+    if "file" not in data:
+        raise MalformedError(f"'file' key not found: '{path}'")
     if "sections" in data:
         # this is a shorthand for defining a single part
         if "parts" in data:
@@ -167,7 +167,7 @@ def _parse_doc_item(
     if not isinstance(parts_data, Sequence):
         raise MalformedError(f"'parts' not a sequence: '{path}'")
 
-    _known_link_keys = {"url", "doc", "glob"}
+    _known_link_keys = {"file", "glob", "url"}
 
     parts = []
     for part_idx, part in enumerate(parts_data):
@@ -186,8 +186,8 @@ def _parse_doc_item(
                     "toctree section contains incompatible keys "
                     f"{link_keys!r}: {path}{part_idx}/{sect_idx}"
                 )
-            if link_keys == {"doc"}:
-                sections.append(RefItem(section["doc"]))
+            if link_keys == {"file"}:
+                sections.append(RefItem(section["file"]))
             elif link_keys == {"glob"}:
                 sections.append(GlobItem(section["glob"]))
             elif link_keys == {"url"}:
@@ -214,15 +214,15 @@ def _parse_doc_item(
         parts.append(toc_item)
 
     try:
-        doc_item = DocItem(docname=data["doc"], title=data.get("title"), parts=parts)
+        doc_item = DocItem(docname=data["file"], title=data.get("title"), parts=parts)
     except TypeError as exc:
         raise MalformedError(f"doc validation: {path}") from exc
 
     docs_data = [
         section
         for part in parts_data
         for section in part["sections"]
-        if "doc" in section
+        if "file" in section
     ]
 
     return (
@@ -239,9 +239,9 @@ def _parse_docs_list(
 ):
     """Parse a list of docs."""
     for doc_data in docs_list:
-        docname = doc_data["doc"]
+        docname = doc_data["file"]
         if docname in site_map:
-            raise MalformedError(f"document used multiple times: {docname}")
+            raise MalformedError(f"document file used multiple times: {docname}")
         child_path = f"{path}{docname}/"
         child_item, child_docs_list = _parse_doc_item(doc_data, defaults, child_path)
         site_map[docname] = child_item
diff --git a/tests/_toc_files/basic.yml b/tests/_toc_files/basic.yml
@@ -1,15 +1,15 @@
 defaults:
   numbered: true
 main:
-  doc: intro
+  file: intro
   title: Introduction
   parts:
     - caption: Part Caption
       sections:
-      - doc: doc1
-      - doc: doc2
-      - doc: doc3
+      - file: doc1
+      - file: doc2
+      - file: doc3
         parts:
         - sections:
-          - doc: doc4
+          - file: doc4
           - url: https://example.com
diff --git a/tests/_toc_files/basic_compressed.yml b/tests/_toc_files/basic_compressed.yml
@@ -1,12 +1,12 @@
 defaults:
   numbered: true
 main:
-  doc: intro
+  file: intro
   title: Introduction
   sections:
-  - doc: doc1
-  - doc: doc2
-  - doc: doc3
+  - file: doc1
+  - file: doc2
+  - file: doc3
     sections:
-    - doc: doc4
+    - file: doc4
     - url: https://example.com
diff --git a/tests/_toc_files/glob.yml b/tests/_toc_files/glob.yml
@@ -1,5 +1,5 @@
 main:
-  doc: intro
+  file: intro
   title: Introduction
   sections:
   - glob: doc*
