| Name | sphinx_external_toc JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | A sphinx extension that allows the site-map to be defined in a single YAML file. |
| upload_time | 2023-12-12 10:26:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
sphinx
extension
toc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinx-external-toc
[![Github-CI][github-ci]][github-link]
[![Coverage Status][codecov-badge]][codecov-link]
[![Code style: black][black-badge]][black-link]
[![PyPI][pypi-badge]][pypi-link]
A sphinx extension that allows the documentation site-map (a.k.a Table of Contents) to be defined external to the documentation files.
As used by [Jupyter Book](https://jupyterbook.org)!
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 site-map structure, within a single YAML file.
It also allows for documents not specified in the ToC to be auto-excluded.
## User Guide
### Sphinx Configuration
Add to your `conf.py`:
```python
extensions = ["sphinx_external_toc"]
external_toc_path = "_toc.yml" # optional, default: _toc.yml
external_toc_exclude_missing = False # optional, default: False
```
Note the `external_toc_path` is always read as a Unix path, and can either be specified relative to the source directory (recommended) or as an absolute path.
### Basic Structure
A minimal ToC defines the top level `root` key, for a single root document file:
```yaml
root: intro
```
The value of the `root` key will be a path to a file, in Unix format (folders split by `/`), relative to the source directory, and can be with or without the file extension.
:::{note}
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 `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.)
- `url`: path for an external URL (starting e.g. `http` or `https`)
:::{important}
Each document file can only occur once in the ToC!
:::
This can proceed recursively to any depth.
```yaml
root: intro
subtrees:
- entries:
- file: doc1
subtrees:
- entries:
- file: doc2
subtrees:
- entries:
- file: doc3
- url: https://example.com
- glob: subfolder/other*
```
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 `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
entries:
- file: doc1
entries:
- file: doc2
entries:
- file: doc3
- url: https://example.com
- glob: subfolder/other*
```
### File and URL titles
By default, the initial header within a `file` document will be used as its title in generated Table of Contents.
With the `title` key you can set an alternative title for a document. and also for `url`:
```yaml
root: intro
subtrees:
- entries:
- file: doc1
title: Document 1 Title
- url: https://example.com
title: Example URL Title
```
### ToC tree options
Each subtree can be configured with a number of options (see also [sphinx `toctree` options](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree)):
- `caption` (string): A title for the whole the subtree, e.g. shown above the subtree in ToCs
- `hidden` (boolean): Whether to show the ToC within (inline of) the document (default `False`).
By default it is appended to the end of the document, but see also the `tableofcontents` directive for positioning of the ToC.
- `maxdepth` (integer): A maximum nesting depth to use when showing the ToC within the document (default -1, meaning infinite).
- `numbered` (boolean or integer): Automatically add numbers to all documents within a subtree (default `False`).
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` 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:
```yaml
root: intro
subtrees:
- caption: Subtree Caption
hidden: False
maxdepth: 1
numbered: True
reversed: False
titlesonly: True
entries:
- file: doc1
subtrees:
- titlesonly: True
entries:
- file: doc2
```
or, if you are using the shorthand for a single subtree, set options under an `options` key:
```yaml
root: intro
options:
caption: Subtree Caption
hidden: False
maxdepth: 1
numbered: True
reversed: False
titlesonly: True
entries:
- file: doc1
options:
titlesonly: True
entries:
- file: doc2
```
You can also use the top-level `defaults` key, to set default options for all subtrees:
```yaml
root: intro
defaults:
titlesonly: True
options:
caption: Subtree Caption
hidden: False
maxdepth: 1
numbered: True
reversed: False
entries:
- file: doc1
entries:
- file: doc2
```
:::{warning}
`numbered` should not generally be used as a default, since numbering cannot be changed by nested subtrees, and sphinx will log a warning.
:::
:::{note}
By default, title numbering restarts for each subtree.
If you want want this numbering to be continuous, check-out the [sphinx-multitoc-numbering extension](https://github.com/executablebooks/sphinx-multitoc-numbering).
:::
### Using different key-mappings
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 `entries` -> `sections`
- Sets the default of `titlesonly` to `true`
- `jb-book`:
- Maps the top-level `subtrees` to `parts`
- Maps the top-level `entries` to `chapters`
- Maps other levels of `entries` to `sections`
- Sets the default of `titlesonly` to `true`
For example:
```yaml
defaults:
titlesonly: true
root: index
subtrees:
- entries:
- file: doc1
entries:
- file: doc2
```
is equivalent to:
```yaml
format: jb-book
root: index
parts:
- chapters:
- file: doc1
sections:
- file: doc2
```
:::{important}
These change in key names do not change the output site-map structure.
:::
## Add a ToC to a page's content
By default, the `toctree` generated per document (one per subtree) are appended to the end of the document and hidden (then, for example, most HTML themes show them in a side-bar).
But if you would like them to be visible at a certain place within the document body, you may do so by using the `tableofcontents` directive:
ReStructuredText:
```restructuredtext
.. tableofcontents::
```
MyST Markdown:
````md
```{tableofcontents}
```
````
Currently, only one `tableofcontents` should be used per page (all `toctree` will be added here), and only if it is a page with child/descendant documents.
Note, this will override the `hidden` option set for a subtree.
## Excluding files not in ToC
By default, Sphinx will build all document files, regardless of whether they are specified in the Table of Contents, if they:
1. Have a file extension relating to a loaded parser (e.g. `.rst` or `.md`)
2. Do not match a pattern in [`exclude_patterns`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns)
To automatically add any document files that do not match a `file` or `glob` in the ToC to the `exclude_patterns` list, add to your `conf.py`:
```python
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.
To see all options:
```console
$ sphinx-etoc --help
Usage: sphinx-etoc [OPTIONS] COMMAND [ARGS]...
Command-line for sphinx-external-toc.
Options:
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
from-project Create a ToC file from a project directory.
migrate Migrate a ToC from a previous revision.
parse Parse a ToC file to a site-map YAML.
to-project Create a project directory from a ToC file.
```
To build a template project from only a ToC file:
```console
$ sphinx-etoc to-project -p path/to/site -e rst path/to/_toc.yml
```
Note, you can also add additional files in `meta`/`create_files` amd append text to the end of files with `meta`/`create_append`, e.g.
```yaml
root: intro
entries:
- glob: doc*
meta:
create_append:
intro: |
This is some
appended text
create_files:
- doc1
- doc2
- doc3
```
To build a ToC file from an existing site:
```console
$ sphinx-etoc from-project path/to/folder
```
Some rules used:
- Files/folders will be skipped if they match a pattern added by `-s` (based on [fnmatch](https://docs.python.org/3/library/fnmatch.html) Unix shell-style wildcards)
- Sub-folders with no content files inside will be skipped
- File and folder names will be sorted by [natural order](https://en.wikipedia.org/wiki/Natural_sort_order)
- If there is a file called `index` (or the name set by `-i`) in any folder, it will be treated as the index file, otherwise the first file by ordering will be used.
The command can also guess a `title` for each file, based on its path:
- The folder name is used for index files, otherwise the file name
- Words are split by `_`
- The first "word" is removed if it is an integer
For example, for a project with files:
```
index.rst
1_a_title.rst
11_another_title.rst
.hidden_file.rst
.hidden_folder/index.rst
1_a_subfolder/index.rst
2_another_subfolder/index.rst
2_another_subfolder/other.rst
3_subfolder/1_no_index.rst
3_subfolder/2_no_index.rst
14_subfolder/index.rst
14_subfolder/subsubfolder/index.rst
14_subfolder/subsubfolder/other.rst
```
will create the ToC:
```console
$ sphinx-etoc from-project path/to/folder -i index -s ".*" -e ".rst" -t
root: index
entries:
- file: 1_a_title
title: A title
- file: 11_another_title
title: Another title
- file: 1_a_subfolder/index
title: A subfolder
- file: 2_another_subfolder/index
title: Another subfolder
entries:
- file: 2_another_subfolder/other
title: Other
- file: 3_subfolder/1_no_index
title: No index
entries:
- file: 3_subfolder/2_no_index
title: No index
- file: 14_subfolder/index
title: Subfolder
entries:
- file: 14_subfolder/subsubfolder/index
title: Subsubfolder
entries:
- file: 14_subfolder/subsubfolder/other
title: Other
```
## API
The ToC file is parsed to a `SiteMap`, which is a `MutableMapping` subclass, with keys representing docnames mapping to a `Document` that stores information on the toctrees it should contain:
```python
import yaml
from sphinx_external_toc.parsing import parse_toc_yaml
path = "path/to/_toc.yml"
site_map = parse_toc_yaml(path)
yaml.dump(site_map.as_json())
```
Would produce e.g.
```yaml
root: intro
documents:
doc1:
docname: doc1
subtrees: []
title: null
intro:
docname: intro
subtrees:
- caption: Subtree Caption
numbered: true
reversed: false
items:
- doc1
titlesonly: true
title: null
meta: {}
```
## Development Notes
Questions / TODOs:
- Add additional top-level keys, e.g. `appendices` (see https://github.com/sphinx-doc/sphinx/issues/2502) and `bibliography`
- Using `external_toc_exclude_missing` to exclude a certain file suffix:
currently if you had files `doc.md` and `doc.rst`, and put `doc.md` in your ToC,
it will add `doc.rst` to the excluded patterns but then, when looking for `doc.md`,
will still select `doc.rst` (since it is first in `source_suffix`).
Maybe open an issue on sphinx, that `doc2path` should respect exclude patterns.
- Integrate https://github.com/executablebooks/sphinx-multitoc-numbering into this extension? (or upstream PR)
- document suppressing warnings
- test against orphan file
- https://github.com/executablebooks/sphinx-book-theme/pull/304
- CLI command to generate toc from existing documentation `toctrees` (and then remove toctree directives)
- test rebuild on toc changes (and document how rebuilds are controlled when toc changes)
- some jupyter-book issues point to potential changes in numbering, based on where the `toctree` is in the document.
So could look into placing it e.g. under the first heading/title
[github-ci]: https://github.com/executablebooks/sphinx-external-toc/workflows/continuous-integration/badge.svg?branch=main
[github-link]: https://github.com/executablebooks/sphinx-external-toc
[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-external-toc/branch/main/graph/badge.svg
[codecov-link]: https://codecov.io/gh/executablebooks/sphinx-external-toc
[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-link]: https://github.com/ambv/black
[pypi-badge]: https://img.shields.io/pypi/v/sphinx-external-toc.svg
[pypi-link]: https://pypi.org/project/sphinx-external-toc
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx_external_toc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "sphinx,extension,toc",
"author": null,
"author_email": "Chris Sewell <chrisj_sewell@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d7/b3/e900bcbb9d0071b928991e00ea70b3e6c6dd774dcf906c043c500e61584c/sphinx_external_toc-1.0.1.tar.gz",
"platform": null,
"description": "# sphinx-external-toc\n\n[![Github-CI][github-ci]][github-link]\n[![Coverage Status][codecov-badge]][codecov-link]\n[![Code style: black][black-badge]][black-link]\n[![PyPI][pypi-badge]][pypi-link]\n\nA sphinx extension that allows the documentation site-map (a.k.a Table of Contents) to be defined external to the documentation files.\nAs used by [Jupyter Book](https://jupyterbook.org)!\n\nIn 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.\n\nThis extension facilitates a **top-down** approach to defining the site-map structure, within a single YAML file.\n\n\n\nIt also allows for documents not specified in the ToC to be auto-excluded.\n\n## User Guide\n\n### Sphinx Configuration\n\nAdd to your `conf.py`:\n\n```python\nextensions = [\"sphinx_external_toc\"]\nexternal_toc_path = \"_toc.yml\" # optional, default: _toc.yml\nexternal_toc_exclude_missing = False # optional, default: False\n```\n\nNote the `external_toc_path` is always read as a Unix path, and can either be specified relative to the source directory (recommended) or as an absolute path.\n\n### Basic Structure\n\nA minimal ToC defines the top level `root` key, for a single root document file:\n\n```yaml\nroot: intro\n```\n\nThe value of the `root` key will be a path to a file, in Unix format (folders split by `/`), relative to the source directory, and can be with or without the file extension.\n\n:::{note}\nThis root file will be set as the [`master_doc`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-master_doc).\n:::\n\nDocument 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:\n\n- `file`: path to a single document file in Unix format, with or without the file extension (as for `root`)\n- `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.)\n- `url`: path for an external URL (starting e.g. `http` or `https`)\n\n:::{important}\nEach document file can only occur once in the ToC!\n:::\n\nThis can proceed recursively to any depth.\n\n```yaml\nroot: intro\nsubtrees:\n- entries:\n - file: doc1\n subtrees:\n - entries:\n - file: doc2\n subtrees:\n - entries:\n - file: doc3\n - url: https://example.com\n - glob: subfolder/other*\n```\n\nThis is equivalent to having a single `toctree` directive in `intro`, containing `doc1`,\nand a single `toctree` directive in `doc1`, with the `:glob:` flag and containing `doc2`, `https://example.com` and `subfolder/other*`.\n\nAs a shorthand, the `entries` key can be at the same level as the `file`, which denotes a document with a single subtree.\nFor example, this file is exactly equivalent to the one above:\n\n```yaml\nroot: intro\nentries:\n- file: doc1\n entries:\n - file: doc2\n entries:\n - file: doc3\n- url: https://example.com\n- glob: subfolder/other*\n```\n\n### File and URL titles\n\nBy default, the initial header within a `file` document will be used as its title in generated Table of Contents.\nWith the `title` key you can set an alternative title for a document. and also for `url`:\n\n```yaml\nroot: intro\nsubtrees:\n- entries:\n - file: doc1\n title: Document 1 Title\n - url: https://example.com\n title: Example URL Title\n```\n\n### ToC tree options\n\nEach subtree can be configured with a number of options (see also [sphinx `toctree` options](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree)):\n\n- `caption` (string): A title for the whole the subtree, e.g. shown above the subtree in ToCs\n- `hidden` (boolean): Whether to show the ToC within (inline of) the document (default `False`).\n By default it is appended to the end of the document, but see also the `tableofcontents` directive for positioning of the ToC.\n- `maxdepth` (integer): A maximum nesting depth to use when showing the ToC within the document (default -1, meaning infinite).\n- `numbered` (boolean or integer): Automatically add numbers to all documents within a subtree (default `False`).\n If set to `True`, all sub-trees will also be numbered based on nesting (e.g. with `1.1` or `1.1.1`),\n or if set to an integer then the numbering will only be applied to that depth.\n- `reversed` (boolean): If `True` then the entries in the subtree will be listed in reverse order (default `False`).\n This can be useful when using `glob` entries.\n- `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`).\n\nThese options can be set at the level of the subtree:\n\n```yaml\nroot: intro\nsubtrees:\n- caption: Subtree Caption\n hidden: False\n maxdepth: 1\n numbered: True\n reversed: False\n titlesonly: True\n entries:\n - file: doc1\n subtrees:\n - titlesonly: True\n entries:\n - file: doc2\n```\n\nor, if you are using the shorthand for a single subtree, set options under an `options` key:\n\n```yaml\nroot: intro\noptions:\n caption: Subtree Caption\n hidden: False\n maxdepth: 1\n numbered: True\n reversed: False\n titlesonly: True\nentries:\n- file: doc1\n options:\n titlesonly: True\n entries:\n - file: doc2\n```\n\nYou can also use the top-level `defaults` key, to set default options for all subtrees:\n\n```yaml\nroot: intro\ndefaults:\n titlesonly: True\noptions:\n caption: Subtree Caption\n hidden: False\n maxdepth: 1\n numbered: True\n reversed: False\nentries:\n- file: doc1\n entries:\n - file: doc2\n```\n\n:::{warning}\n`numbered` should not generally be used as a default, since numbering cannot be changed by nested subtrees, and sphinx will log a warning.\n:::\n\n:::{note}\nBy default, title numbering restarts for each subtree.\nIf you want want this numbering to be continuous, check-out the [sphinx-multitoc-numbering extension](https://github.com/executablebooks/sphinx-multitoc-numbering).\n:::\n\n### Using different key-mappings\n\nFor 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).\n\nThe `format` key can be used to provide such mappings (and also initial defaults).\nCurrently available:\n\n- `jb-article`:\n - Maps `entries` -> `sections`\n - Sets the default of `titlesonly` to `true`\n- `jb-book`:\n - Maps the top-level `subtrees` to `parts`\n - Maps the top-level `entries` to `chapters`\n - Maps other levels of `entries` to `sections`\n - Sets the default of `titlesonly` to `true`\n\nFor example:\n\n```yaml\ndefaults:\n titlesonly: true\nroot: index\nsubtrees:\n- entries:\n - file: doc1\n entries:\n - file: doc2\n```\n\nis equivalent to:\n\n```yaml\nformat: jb-book\nroot: index\nparts:\n- chapters:\n - file: doc1\n sections:\n - file: doc2\n```\n\n:::{important}\nThese change in key names do not change the output site-map structure.\n:::\n\n## Add a ToC to a page's content\n\nBy default, the `toctree` generated per document (one per subtree) are appended to the end of the document and hidden (then, for example, most HTML themes show them in a side-bar).\nBut if you would like them to be visible at a certain place within the document body, you may do so by using the `tableofcontents` directive:\n\nReStructuredText:\n\n```restructuredtext\n.. tableofcontents::\n```\n\nMyST Markdown:\n\n````md\n```{tableofcontents}\n```\n````\n\nCurrently, only one `tableofcontents` should be used per page (all `toctree` will be added here), and only if it is a page with child/descendant documents.\n\nNote, this will override the `hidden` option set for a subtree.\n\n## Excluding files not in ToC\n\nBy default, Sphinx will build all document files, regardless of whether they are specified in the Table of Contents, if they:\n\n1. Have a file extension relating to a loaded parser (e.g. `.rst` or `.md`)\n2. Do not match a pattern in [`exclude_patterns`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns)\n\nTo automatically add any document files that do not match a `file` or `glob` in the ToC to the `exclude_patterns` list, add to your `conf.py`:\n\n```python\nexternal_toc_exclude_missing = True\n```\n\nNote 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.\nYou should exclude these folders explicitly.\n\n:::{important}\nThis feature is not currently compatible with [orphan files](https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#metadata).\n:::\n\n## Command-line\n\nThis package comes with the `sphinx-etoc` command-line program, with some additional tools.\n\nTo see all options:\n\n```console\n$ sphinx-etoc --help\nUsage: sphinx-etoc [OPTIONS] COMMAND [ARGS]...\n\n Command-line for sphinx-external-toc.\n\nOptions:\n --version Show the version and exit.\n -h, --help Show this message and exit.\n\nCommands:\n from-project Create a ToC file from a project directory.\n migrate Migrate a ToC from a previous revision.\n parse Parse a ToC file to a site-map YAML.\n to-project Create a project directory from a ToC file.\n```\n\nTo build a template project from only a ToC file:\n\n```console\n$ sphinx-etoc to-project -p path/to/site -e rst path/to/_toc.yml\n```\n\nNote, you can also add additional files in `meta`/`create_files` amd append text to the end of files with `meta`/`create_append`, e.g.\n\n```yaml\nroot: intro\nentries:\n- glob: doc*\nmeta:\n create_append:\n intro: |\n This is some\n appended text\n create_files:\n - doc1\n - doc2\n - doc3\n```\n\nTo build a ToC file from an existing site:\n\n```console\n$ sphinx-etoc from-project path/to/folder\n```\n\nSome rules used:\n\n- Files/folders will be skipped if they match a pattern added by `-s` (based on [fnmatch](https://docs.python.org/3/library/fnmatch.html) Unix shell-style wildcards)\n- Sub-folders with no content files inside will be skipped\n- File and folder names will be sorted by [natural order](https://en.wikipedia.org/wiki/Natural_sort_order)\n- If there is a file called `index` (or the name set by `-i`) in any folder, it will be treated as the index file, otherwise the first file by ordering will be used.\n\nThe command can also guess a `title` for each file, based on its path:\n\n- The folder name is used for index files, otherwise the file name\n- Words are split by `_`\n- The first \"word\" is removed if it is an integer\n\nFor example, for a project with files:\n\n```\nindex.rst\n1_a_title.rst\n11_another_title.rst\n.hidden_file.rst\n.hidden_folder/index.rst\n1_a_subfolder/index.rst\n2_another_subfolder/index.rst\n2_another_subfolder/other.rst\n3_subfolder/1_no_index.rst\n3_subfolder/2_no_index.rst\n14_subfolder/index.rst\n14_subfolder/subsubfolder/index.rst\n14_subfolder/subsubfolder/other.rst\n```\n\nwill create the ToC:\n\n```console\n$ sphinx-etoc from-project path/to/folder -i index -s \".*\" -e \".rst\" -t\nroot: index\nentries:\n- file: 1_a_title\n title: A title\n- file: 11_another_title\n title: Another title\n- file: 1_a_subfolder/index\n title: A subfolder\n- file: 2_another_subfolder/index\n title: Another subfolder\n entries:\n - file: 2_another_subfolder/other\n title: Other\n- file: 3_subfolder/1_no_index\n title: No index\n entries:\n - file: 3_subfolder/2_no_index\n title: No index\n- file: 14_subfolder/index\n title: Subfolder\n entries:\n - file: 14_subfolder/subsubfolder/index\n title: Subsubfolder\n entries:\n - file: 14_subfolder/subsubfolder/other\n title: Other\n```\n\n## API\n\nThe ToC file is parsed to a `SiteMap`, which is a `MutableMapping` subclass, with keys representing docnames mapping to a `Document` that stores information on the toctrees it should contain:\n\n```python\nimport yaml\nfrom sphinx_external_toc.parsing import parse_toc_yaml\npath = \"path/to/_toc.yml\"\nsite_map = parse_toc_yaml(path)\nyaml.dump(site_map.as_json())\n```\n\nWould produce e.g.\n\n```yaml\nroot: intro\ndocuments:\n doc1:\n docname: doc1\n subtrees: []\n title: null\n intro:\n docname: intro\n subtrees:\n - caption: Subtree Caption\n numbered: true\n reversed: false\n items:\n - doc1\n titlesonly: true\n title: null\nmeta: {}\n```\n\n## Development Notes\n\nQuestions / TODOs:\n\n- Add additional top-level keys, e.g. `appendices` (see https://github.com/sphinx-doc/sphinx/issues/2502) and `bibliography`\n- Using `external_toc_exclude_missing` to exclude a certain file suffix:\n currently if you had files `doc.md` and `doc.rst`, and put `doc.md` in your ToC,\n it will add `doc.rst` to the excluded patterns but then, when looking for `doc.md`,\n will still select `doc.rst` (since it is first in `source_suffix`).\n Maybe open an issue on sphinx, that `doc2path` should respect exclude patterns.\n- Integrate https://github.com/executablebooks/sphinx-multitoc-numbering into this extension? (or upstream PR)\n- document suppressing warnings\n- test against orphan file\n- https://github.com/executablebooks/sphinx-book-theme/pull/304\n- CLI command to generate toc from existing documentation `toctrees` (and then remove toctree directives)\n- test rebuild on toc changes (and document how rebuilds are controlled when toc changes)\n- some jupyter-book issues point to potential changes in numbering, based on where the `toctree` is in the document.\n So could look into placing it e.g. under the first heading/title\n\n[github-ci]: https://github.com/executablebooks/sphinx-external-toc/workflows/continuous-integration/badge.svg?branch=main\n[github-link]: https://github.com/executablebooks/sphinx-external-toc\n[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-external-toc/branch/main/graph/badge.svg\n[codecov-link]: https://codecov.io/gh/executablebooks/sphinx-external-toc\n[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg\n[black-link]: https://github.com/ambv/black\n[pypi-badge]: https://img.shields.io/pypi/v/sphinx-external-toc.svg\n[pypi-link]: https://pypi.org/project/sphinx-external-toc\n",
"bugtrack_url": null,
"license": null,
"summary": "A sphinx extension that allows the site-map to be defined in a single YAML file.",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://sphinx-external-toc.readthedocs.io",
"Homepage": "https://github.com/executablebooks/sphinx-external-toc"
},
"split_keywords": [
"sphinx",
"extension",
"toc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5f9acb412957424012869b43a5aa3d95ccebcac737dafc5a545ce15bb8037f6e",
"md5": "64653a351ebf7a32311b8301e25d0a01",
"sha256": "d9e02d50731dee9697c1887e4f8b361e7b86d38241f0e66bd5a9f4096779646f"
},
"downloads": -1,
"filename": "sphinx_external_toc-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64653a351ebf7a32311b8301e25d0a01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 26677,
"upload_time": "2023-12-12T10:26:52",
"upload_time_iso_8601": "2023-12-12T10:26:52.017621Z",
"url": "https://files.pythonhosted.org/packages/5f/9a/cb412957424012869b43a5aa3d95ccebcac737dafc5a545ce15bb8037f6e/sphinx_external_toc-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d7b3e900bcbb9d0071b928991e00ea70b3e6c6dd774dcf906c043c500e61584c",
"md5": "7d66d495eeacb3f67d190cb20347acef",
"sha256": "a7d2c63cc47ec688546443b28bc4ef466121827ef3dc7bb509de354bad4ea2e0"
},
"downloads": -1,
"filename": "sphinx_external_toc-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7d66d495eeacb3f67d190cb20347acef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32755,
"upload_time": "2023-12-12T10:26:53",
"upload_time_iso_8601": "2023-12-12T10:26:53.951468Z",
"url": "https://files.pythonhosted.org/packages/d7/b3/e900bcbb9d0071b928991e00ea70b3e6c6dd774dcf906c043c500e61584c/sphinx_external_toc-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-12 10:26:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "executablebooks",
"github_project": "sphinx-external-toc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx_external_toc"
}
