Skip to content

Writing Custom Parser Plugins

A doc2dash parser plugin has three jobs:

  1. Detect whether it can parse a directory and extract an appropriate name for the docset.
  2. Parse a directory and tell doc2dash about all entries that should be indexed.
  3. Patch files such that Dash can generate per-file tables of contents.

For that, it must implement the Parser protocol:

Parser

Bases: Protocol

A doc2dash documentation parser.

Attributes:

Name Type Description
name str

The name of this parser. Used in user-facing output.

detect(path) staticmethod

Check whether path can be parsed by this parser.

Parameters:

Name Type Description Default
path Path

The path to the documentation.

 required

Returns:

Type Description
str | None

The name of the documentation or None if it’s not ours.

__init__(source)

Initialize parser.

If this parser’s detect() static method indicates that source belongs to it, doc2dash instantiates it as parser_type(path).

Parameters:

Name Type Description Default
source Path

The path to the documentation that will be parsed.

 required

parse()

Parse the path that this parser was initialized with and yield a ParserEntry for each entry it finds.

Returns:

Type Description
None

A generator that yields ParserEntrys.

make_patcher_for_file(path)

A context manager that prepares for patching path and returns a Patcher callable.

Parameters:

Name Type Description Default
path Path

path to file to patch

 required

Yields:

Type Description
Patcher

A patch function.

Patcher

Bases: Protocol

A callable that patches the file that it belongs to and returns whether it did.

__call__(name, type, anchor, ref)

Parameters:

Name Type Description Default
name str

name of the entry

 required
type EntryType

the type of the entry

 required
anchor str

the place to add ref

 required
ref str

the reference to add before anchor

 required

Returns:

Type Description
bool

Whether it found the anchor and did anything.

ParserEntry

A symbol to be indexed, as found by Parser’s parse() method.

name instance-attribute

The full display name of the index entry.

type instance-attribute

The type of the entry.

path instance-attribute

Full path including anchor (#). E.g. api.rst#print

EntryType

Bases: Enum

Possible types for entries.

Pick from https://kapeli.com/docsets#supportedentrytypes.

To use your custom parser, you have to invoke doc2dash with the --parser option and specify the importable path to it.

Example

Often, it’s the easiest to get started by looking at existing parsers. Conveniently, doc2dash ships one:

The intersphinx parser uses a machine-readable format to extract the necessary metadata.