📚 DOCS: Add full documentation (#41)

Author: chrisjsewell

README.md

@@ -11,7 +11,7 @@ In normal Sphinx documentation, the documentation site-map is defined *via* a bo
 
 This extension facilitates a **top-down** approach to defining the site-map structure, within a single YAML file.
 
-![ToC graphic](toc-graphic.png)
+![ToC graphic](docs/toc-graphic.png)
 
 It also allows for documents not specified in the ToC to be auto-excluded.
 

docs/_toc.yml

@@ -1,17 +1,18 @@
 root: intro
-defaults:
-  titlesonly: false
 subtrees:
-- caption: Part 1
+- caption: User Guide
   numbered: true
   entries:
-  - file: doc1
-  - file: doc2
+  - file: user_guide/sphinx
+  - file: user_guide/cli
+  - file: user_guide/api
+- caption: Example
+  entries:
+  - file: example/index
     entries:
-    - file: subfolder/doc3
-    - url: https://example.com
-      title: Example Link
-- caption: Part 2
-  numbered: true
+    - file: example/subfolder/page
+    - glob: example/globfolder/*
+- caption: Links
   entries:
-  - glob: subglobs/glob*
+  - title: GitHub Repository
+    url: https://github.com/executablebooks/sphinx-external-toc

docs/conf.py

@@ -1,15 +1,18 @@
-# Configuration file for the Sphinx documentation builder.
+"""Configuration file for the Sphinx documentation builder."""
 
 project = "Sphinx External ToC"
 copyright = "2021, Executable Book Project"
 author = "Executable Book Project"
 
 extensions = ["myst_parser", "sphinx_external_toc"]
 
+myst_enable_extensions = ["colon_fence", "html_image"]
+
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 external_toc_exclude_missing = True
 
 html_theme = "sphinx_book_theme"
+html_title = project
 html_theme_options = {
     "home_page_in_toc": True,
     "use_edit_page_button": True,

docs/doc1.md

@@ -0,0 +1,3 @@
+# Sub-section Glob Page 1
+
+A page added via globbing.

docs/doc2.md

@@ -0,0 +1,3 @@
+# Sub-section Glob Page 2
+
+Another page added via globbing.

docs/example/globfolder/page1.md

@@ -0,0 +1,4 @@
+# Example Project
+
+These pages provide an example of different aspects of the ToC.
+See this projects `_toc.yml` for how they are added.

docs/example/globfolder/page2.md

@@ -0,0 +1,3 @@
+# Sub-section Page
+
+This is a page of a subsection.

docs/example/index.md

@@ -1,10 +1,18 @@
-# sphinx-external-toc [IN-DEVELOPMENT]
+# sphinx-external-toc
 
-A sphinx extension that allows the documentation toctree to be defined in a single YAML file.
+A sphinx extension that allows the documentation site-map (a.k.a Table of Contents) to be defined external to the documentation files.
 
-In normal Sphinx documentation, the documentation structure is defined *via* a bottom-up approach - adding [`toctree` directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) within pages of the documentation.
+In normal Sphinx documentation, the documentation site-map is defined *via* a bottom-up approach - adding [`toctree` directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) within pages of the documentation.
 
-This extension facilitates a **top-down** approach to defining the structure, within a single file that is external to the documentation.
+This extension facilitates a **top-down** approach to defining the site-map structure, within a single YAML file.
+
+:::{figure-md}
+<img src="toc-graphic.png" alt="ToC graphic" width="600px" />
+
+Example ToC
+:::
+
+It also allows for documents not specified in the ToC to be auto-excluded.
 
 ```{tableofcontents}
 ```