pestifer.sphinxext.toctree_util module

Modifies toctree directives in documentation when pestifer modify-package is used to add or remove examples. Written substantially by ChatGPT, with some modifications.

pestifer.sphinxext.toctree_util.detect_common_prefix(entries)[source]

Detects the common prefix in a list of entries. If all entries share a common prefix, returns that prefix with a trailing separator. If no common prefix exists, returns None.

pestifer.sphinxext.toctree_util.find_toctree_block(lines)[source]

Finds the start and end indices of the toctree block in the RST file lines. The toctree block starts with “.. toctree::” and may have options before the entries.

Parameters:

lines (list of str) – The lines of the RST file.

Returns:

A tuple containing the start index of the toctree block, the start index of the entries, and the end index of the entries.

Return type:

tuple

Raises:

ValueError – If no toctree block is found in the lines.

pestifer.sphinxext.toctree_util.get_name_from_toctree(filepath, match_str: str)[source]

Retrieves the name of the entry at the specified index from the toctree in an RST file.

Parameters:

  • filepath (str) – The path to the RST file.

  • match_str (str) – The string to match against the entry names.

Returns:

The name of the entry that matches the specified string.

Return type:

str

Raises:

IndexError – If the index is out of range for the entries in the toctree.

pestifer.sphinxext.toctree_util.get_num_entries_in_toctree(filepath)[source]

Retrieves the number of entries in the toctree block of an RST file.

Parameters:

filepath (str) – The path to the RST file.

Returns:

The number of entries in the toctree block.

Return type:

int

Raises:

ValueError – If no toctree block is found in the file.

pestifer.sphinxext.toctree_util.modify_entries(entries, action, target: str = None, new_entry=None, common_prefix=None)[source]

Modifies the list of entries based on the specified action.

Parameters:

  • entries (list of str) – The current list of entries in the toctree.

  • action (str) – The action to perform: “delete”, “update”, or “append”.

  • target (str, optional) – The entry to delete or update if action is “delete” or “update”, respectively. Required for “delete” and “update” actions.

  • new_entry (str, optional) – The new entry to append. Required for “append” actions.

Returns:

The modified list of entries in the toctree.

Return type:

list of str

pestifer.sphinxext.toctree_util.modify_toctree(filepath, action, target=None, new_entry=None, common_prefix=None)[source]

Modifies the toctree block in a reStructuredText (RST) file based on the specified action.

Parameters:

  • filepath (str) – The path to the RST file to modify.

  • action (str) – The action to perform: “delete”, “update”, or “append”.

  • target (str, optional) – The entry to modify (delete, update, or append before/after). Required for “delete”, “append”, and “update” actions.

  • new_entry (str, optional) – The new entry to add or append. Required for “append” and “update” actions.

  • index (int, optional) – The 1-based index at which to append the new entry or update an existing entry. Required for “append” and “update” actions.

pestifer.sphinxext.toctree_util.parse_toctree_entries(lines: list[str], entry_start: int, entry_end: int) → list[str][source]

Parses the entries from the toctree block in the RST file lines.

Parameters:

  • lines (list of str) – The lines of the RST file.

  • entry_start (int) – The start index of the entries in the toctree block.

  • entry_end (int) – The end index of the entries in the toctree block.

Returns:

A list of entries from the toctree block, stripped of leading and trailing whitespace.

Return type:

list of str

pestifer.sphinxext.toctree_util.read_rst_file(filepath)[source]

Reads a reStructuredText (RST) file and returns its lines.

Parameters:

filepath (str) – The path to the RST file to read.

Returns:

A list of lines from the RST file.

Return type:

list of str

pestifer.sphinxext.toctree_util.reconstruct_toctree_block(lines, start, entry_start, entry_end, new_entries)[source]

Reconstructs the toctree block in the RST file lines with the updated entries

Parameters:

  • lines (list of str) – The original lines of the RST file.

  • start (int) – The start index of the toctree block.

  • entry_start (int) – The start index of the entries in the toctree block.

  • entry_end (int) – The end index of the entries in the toctree block.

  • new_entries (list of str) – The new entries to be included in the toctree block.

Returns:

The lines of the RST file with the updated toctree block.

Return type:

list of str

pestifer.sphinxext.toctree_util.write_rst_file(filepath, lines)[source]

Writes a list of lines to a reStructuredText (RST) file.

Parameters:

  • filepath (str) – The path to the RST file to write.

  • lines (list of str) – The lines to write to the RST file.