View sphinx_external_toc on Snyk Open Source Advisor (2023)

View sphinx_external_toc on Snyk Open Source Advisor (1)View sphinx_external_toc on Snyk Open Source Advisor (2)View sphinx_external_toc on Snyk Open Source Advisor (3)View sphinx_external_toc on Snyk Open Source Advisor (4)

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!

In normal Sphinx documentation, the documentation site-map is defined via a bottom-up approach - adding toctree directives within pages of the documentation.

This extension facilitates a top-down approach to defining the site-map structure, within a single YAML file.

View sphinx_external_toc on Snyk Open Source Advisor (5)

It also allows for documents not specified in the ToC to be auto-excluded.

User Guide

Sphinx Configuration

Add to your

extensions = ["sphinx_external_toc"]external_toc_path = "_toc.yml" # optional, default: _toc.ymlexternal_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:

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.:::

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, 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.

root: introsubtrees:- entries: - file: doc1 subtrees: - entries: - file: doc2 subtrees: - entries: - file: doc3 - url: - 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, 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:

root: introentries:- file: doc1 entries: - file: doc2 entries: - file: doc3- url: 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:

root: introsubtrees:- entries: - file: doc1 title: Document 1 Title - url: title: Example URL Title

ToC tree options

Each subtree can be configured with a number of options (see also sphinx toctree options):

  • 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:

root: introsubtrees:- 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:

root: introoptions: caption: Subtree Caption hidden: False maxdepth: 1 numbered: True reversed: False titlesonly: Trueentries:- file: doc1 options: titlesonly: True entries: - file: doc2

You can also use the top-level defaults key, to set default options for all subtrees:

root: introdefaults: titlesonly: Trueoptions: caption: Subtree Caption hidden: False maxdepth: 1 numbered: True reversed: Falseentries:- 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.:::

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.

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:

defaults: titlesonly: trueroot: indexsubtrees:- entries: - file: doc1 entries: - file: doc2

is equivalent to:

format: jb-bookroot: indexparts:- 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:


.. tableofcontents::

MyST Markdown:


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

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

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.:::


This package comes with the sphinx-etoc command-line program, with some additional tools.

To see all options:

$ sphinx-etoc --helpUsage: 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:

$ 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.

root: introentries:- 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:

$ 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 Unix shell-style wildcards)
  • Sub-folders with no content files inside will be skipped
  • File and folder names will be sorted by natural 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:


will create the ToC:

$ sphinx-etoc from-project path/to/folder -i index -s ".*" -e ".rst" -troot: indexentries:- 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


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:

import yamlfrom sphinx_external_toc.parsing import parse_toc_yamlpath = "path/to/_toc.yml"site_map = parse_toc_yaml(path)yaml.dump(site_map.as_json())

Would produce e.g.

root: introdocuments: doc1: docname: doc1 subtrees: [] title: null intro: docname: intro subtrees: - caption: Subtree Caption numbered: true reversed: false items: - doc1 titlesonly: true title: nullmeta: {}

Development Notes

Questions / TODOs:

  • Add additional top-level keys, e.g. appendices (see and bibliography
  • Using external_toc_exclude_missing to exclude a certain file suffix:currently if you had files and doc.rst, and put in your ToC,it will add doc.rst to the excluded patterns but then, when looking for,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 into this extension? (or upstream PR)
  • document suppressing warnings
  • test against orphan file
  • 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


What is SNYK open source and SNYK code? ›

Snyk Open Source allows you to find and fix vulnerabilities in the open source libraries used by your applications. It also allows you to find and address licensing issues in (or caused by) these open source libraries. Snyk Open Source is available in many common languages and platforms.

How to check npm package health? ›

  1. Features. Tells you what's out of date. Provides a link to the package's documentation so you can decide if you want the update. ...
  2. Requirements. Node >= 10.9.0.
  3. On the command line. This is the easiest way to use npm-check .
  4. Install. $ npm install -g npm-check.
  5. Use. $ npm-check. ...
  6. Options. Usage $ npm-check.

What is the rating of SNYK package? ›

PeerSpot users give Snyk an average rating of 8.0 out of 10.

How do I find open-source code? ›

Finding open-source code & programs

The largest repository for open source code projects in the life sciences is currently GitHub. GitHub also has a spin-off environment called GitLab . GitHub allows browsing by topic. Browsing by "biology" or "medicine" can be helpful for discovering projects in the life sciences.

How do I run a Snyk code? ›

You can use the following commands to run tests with the Snyk CLI:
  1. Scan open-source code with snyk test .
  2. Scan application code with snyk code test .
  3. Scan container images with snyk container test .
  4. Scan Infrastructure as Code (IaC) files with snyk iac test .

How to view npm package code? ›

If you haven't installed npm, with the current public API, you can also access the information about a package in the npm registry from the URL<package-name>/ . Then you can navigate the JSON at versions > (version number) > dist > tarball to get the URL of the code archive and download it.

How to see npm package code? ›

To view the npm global packages list and their dependencies, you can run the following npm list command followed by the “-g” flag where g stands for global. As you can see in the above result, all the global packages are displayed in a tree-like structure.

How to view npm installed packages? ›

Use the npm list to show the installed packages in the current project as a dependency tree. Use npm list --depth=n to show the dependency tree with a specified depth. Use npm list --prod to show packages in the dependencies . Use npm list --dev to show packages in the devDependencies .

Is Snyk a vulnerability scanner? ›

Snyk is a platform allowing you to scan, prioritize, and fix security vulnerabilities in your own code, open source dependencies, container images, and Infrastructure as Code (IaC) configurations.

Is Snyk an Israeli company? ›

Founded in 2015 by Israeli entrepreneurs Guy Podjarny, Assaf Hefetz, and Danny Grander, Snyk helps software developers and companies integrate security solutions into their workflows as they are building applications from code to cloud to protect them against sophisticated cyber attacks.

Does Snyk scan code? ›

Snyk scans your code for quality and security issues and get fix advice right in your IDE.

Can I copy code from open source? ›

While most of the open source licenses allow you to copy and paste code in your own projects the way you like, but some of them come with some restrictions. A whopping 63% of developers don't read or understand that licensing is a major issue when it comes to copy and paste publicly available code in their projects.

Can I use code from open source? ›

Absolutely. All Open Source software can be used for commercial purpose; the Open Source Definition guarantees this. You can even sell Open Source software. However, note that commercial is not the same as proprietary.

What is source code in open source? ›

Open source software is software with source code that anyone can inspect, modify, and enhance. "Source code" is the part of software that most computer users don't ever see; it's the code computer programmers can manipulate to change how a piece of software—a "program" or "application"—works.

How do I get a Snyk token? ›

To obtain your Snyk API token via the Web UI:
  1. On the Web UI, Select Account settings from the drop down at the bottom of the left navigation.
  2. On the Account Settings page > General > Auth Token section, click inside the KEY box to display your API token:

Can you run Snyk locally? ›

The Snyk CLI brings the functionality of Snyk into your development workflow. You can run the CLI locally or in your CI/CD pipeline.

How to work with Snyk? ›

Ensure you have:
  1. ​Created a Snyk account.
  2. ​Set up integration with your code repository on a supported system such as GitHub.
  3. ​Imported a Snyk Project for scanning​

Where is npm source code? ›

you can find the source code also at github. you can find the github page of each package on search the pakcage you want on the search bar, click enter, click on the package link and from the right side you could see the link to github.

What is the difference between npm view and npm list? ›

npm view <package> version - returns the latest available version on the package. npm list --depth=0 - returns versions of all installed modules without dependencies. npm list - returns versions of all modules and dependencies. npm view <package> version, goes to the npm remote registry, not local filesystem...

How to check which node npm is using? ›

Just type npm version in your command line and it will display all the version details about node, npm, v8 engine etc.

What is npm source code? ›

The npm Registry is a public collection of packages of open-source code for Node. js, front-end web apps, mobile apps, robots, routers, and countless other needs of the JavaScript community. npm is the command line client that allows developers to install and publish those packages.

What is the difference between npm and NuGet? ›

Npm installs and tracks JavaScript dependencies. NuGet manages dependencies for . NET projects. Gradle manages dependencies and the build process for Java projects.

How to check npm version in Linux? ›

To see if NPM is installed, type npm -v in the terminal. This should print the version number, so you'll see something like this: 2.1. 17.

How do I see all node versions installed? ›

Step 1: check your nodejs version using node –version command. Step 2: go to browser and search for nvm for windows. This is the nodejs version manager for windows that is a pre-requisite to download followed by installing the exe file. Step 3: Check number of node versions installed on terminal using nvm list command.

What does npm view do? ›

Description. This command shows data about a package and prints it to stdout.

Is there a GUI for npm? ›

npm-gui is a convenient tool for managing javascript project dependencies listed in package. json . Under the hood, it will transparently use npm , pnpm , or yarn commands to install, remove or update dependencies (to use yarn it requires the yarn. lock file to be present in the project folder.)

What files does Snyk scan? ›

Snyk Open Source scans your manifest files. Based on the scan, Snyk creates a hierarchical tree of the structure represented in the manifest file: both its direct and indirect (transitive) dependencies and the points at which the different packages are introduced.

Which branch does Snyk scan? ›

Today Snyk monitors the default branch. So if a repo is set to point at `develop` by default then Snyk would do pull requests against `develop`.

What data does Snyk collect? ›

User data - Snyk stores user information required to access and use the platform. Examples: user name, IDs (for example, GitHub user ID), email address, IP address.

Who is Snyk owned by? ›

Snyk is a technology company offering a software development security platform using open-source code. Snyk was founded in 2015 by Assaf Hefetz, Danny Grander, and Guy Podjarny.

Is Snyk a unicorn? ›

Cybersecurity unicorn Snyk announced on Thursday that it is laying off another 128 employees.

Is Snyk public or private? ›


How does Snyk find vulnerabilities? ›

Snyk (pronounced sneak) is a developer security platform for securing code, dependencies, containers, and infrastructure as code. It scans your code, reads through it, and tells you if you have any vulnerabilities in your code.

Is Snyk open source free? ›

Snyk has always offered individual developers free access to our core tools and vulnerability database.

What problem does Snyk solve? ›

Snyk helps you to fix vulnerabilities, by upgrading the direct dependencies to a vulnerability-free version, or by patching the vulnerability. After Snyk scans your Projects, scan results allow you to resolve those issues in your code, with the help of clear suggestions and explanations.

What is Snyk code? ›

Snyk Code is developer-first - embedding SAST as part of the development process, enabling developers to build software securely during the coding stage, and not trying to find and fix problems after the code is compiled.

What is the difference between open source code and source code? ›

With closed source software (also known as proprietary software), the public is not given access to the source code, so they can't see or modify it in any way. But with open source software, the source code is publicly available to anyone who wants it, and programmers can read or change that code if they desire.

What is open source source code? ›

Open source code is usually stored in a public repository and shared publicly. Anyone can access the repository to use the code independently or contribute improvements to the design and functionality of the overall project. OSS usually comes with a distribution license.

What language is Snyk written in? ›

Snyk Code currently supports the following programming languages: C# C/C++ (Beta) Go.

Can Snyk scan source code? ›

Snyk scans your code for quality and security issues and get fix advice right in your IDE.

Is Snyk code free? ›

Snyk functionality is available with several pricing plans: Free: For individual developers and small teams looking to secure while they build. Limited tests. Team: For dev teams looking to build security into their development process with shared visibility into projects.

Is it OK to copy open source code? ›

While most of the open source licenses allow you to copy and paste code in your own projects the way you like, but some of them come with some restrictions. A whopping 63% of developers don't read or understand that licensing is a major issue when it comes to copy and paste publicly available code in their projects.

Is it legal to use open source code? ›

Absolutely. All Open Source software can be used for commercial purpose; the Open Source Definition guarantees this. You can even sell Open Source software. However, note that commercial is not the same as proprietary.

Do you cite open source code? ›

Writing code is similar to academic writing in that when you use or adapt code developed by someone else as part of your project, you must cite your source.

What are 3 examples of open source? ›

10.4 Examples of Open Source Software
  • Firefox—a Web browser that competes with Internet Explorer.
  • OpenOffice—a competitor to Microsoft Office.
  • Gimp—a graphic tool with features found in Photoshop.
  • Alfresco—collaboration software that competes with Microsoft Sharepoint and EMC's Documentum.

What is source code and how do you use it? ›

Source code is generally understood to mean programming statements that are created by a programmer with a text editor or a visual programming tool and then saved in a file. Object code generally refers to the output, a compiled file, which is produced when the Source Code is compiled with a C compiler.

What is source code with example? ›

As an example, when a programmer types a sequence of C programming language statements into Windows Notepad and saves the sequence as a text file, the text file now contains source code. Source code and object code are sometimes referred to as the before and after versions of a compiled computer program.

Does Google use Snyk? ›

Snyk integrations with your Google Cloud Projects to find issues in your cloud configurations and generate cloud context to help you prioritize your vulnerabilities. You can onboard a Google Cloud account to Snyk using the following methods: ​Snyk Web UI​

How many languages does Snyk support? ›

Snyk supports: JavaScript, Java (Gradle, Maven), . NET, Python, Golang, Swift, Objective-C (CocoaPods), Scala, Ruby, PHP, Bazel, Terraform, CloudFormation, Azure Resource Manager, Kubernetes, and Dockerfiles.


Top Articles
Latest Posts
Article information

Author: Golda Nolan II

Last Updated: 28/12/2023

Views: 6283

Rating: 4.8 / 5 (78 voted)

Reviews: 93% of readers found this page helpful

Author information

Name: Golda Nolan II

Birthday: 1998-05-14

Address: Suite 369 9754 Roberts Pines, West Benitaburgh, NM 69180-7958

Phone: +522993866487

Job: Sales Executive

Hobby: Worldbuilding, Shopping, Quilting, Cooking, Homebrewing, Leather crafting, Pet

Introduction: My name is Golda Nolan II, I am a thoughtful, clever, cute, jolly, brave, powerful, splendid person who loves writing and wants to share my knowledge and understanding with you.