Utils#
Utility functions for Fortran lexers and Sphinx integration.
- as_chars(value) list[str][source]#
Normalize a config value into a list of single-character strings.
- collect_fortran_source_files(*, confdir: Path, roots: Sequence[str], extensions: set[str], excludes: Sequence[str] = ()) list[str][source]#
Collect Fortran source files from roots, honoring excludes.
roots may be files, directories, or glob patterns (relative to confdir).
excludes may be files, directories, or glob patterns (relative to confdir).
extensions is a set of allowed suffixes (lower-cased). Empty means “allow any”.
Returns a deterministic sorted list of file paths as strings.
- collect_fortran_source_files_from_config(*, confdir: Path, config) list[str][source]#
Collect sources using standard Sphinx config names.
This is intentionally Sphinx-independent: config can be any object with fortran_sources, fortran_sources_exclude, and fortran_file_extensions attributes.
- dedent_doc(lines: Sequence[str]) str | None[source]#
Join the lines of a doc block, removing their common indentation and the surrounding blank lines. Returns None for an empty block.
- doc_markers_from_doc_chars(doc_chars) list[str][source]#
Convert fortran_doc_chars to concrete doc markers.
Configured fortran_doc_chars is a collection of single characters like [‘>’]. A doc marker is the two-character string that must appear at the start of a comment line, like !>.
Raises ValueError if any entry is not a single character.
- extract_predoc_before_line(lines: Sequence[str], idx: int, *, doc_markers: Sequence[str]) str | None[source]#
Extract contiguous doc lines immediately preceding idx (0-based).
- extract_use_dependencies(source: str) list[str][source]#
Extract unique module names from USE statements (best-effort).
- find_inline_doc(line: str, doc_markers: Sequence[str]) tuple[int, str] | None[source]#
Return (pos, marker) for the earliest inline doc marker, else None.
- is_doc_line(line: str, doc_markers: Sequence[str]) str | None[source]#
Return doc text if the line is a doc line, else None.
Only the single space or tab separating the marker from the text is removed: further indentation is meaningful in reST (list item continuations, directive bodies) and is preserved. Use dedent_doc on the lines of a doc block to remove the indentation they all share.
- read_lines_utf8(path: str | Path) list[str][source]#
Read a text file as UTF-8 lines, replacing invalid sequences.