diplodocus 0.15.0

Build coherent documentation websites for polyglot software projects.
Documentation
use crate::diagnostics::{Diagnostic, DiagnosticCode, Severity};
use crate::documents::{AuthoredFormat, parse_authored_document};
use crate::ir::{Attributes, Block, Inline, SourceSpan};

pub(super) fn parse_line(
    text: &str,
    offset: usize,
    diagnostics: &mut Vec<Diagnostic>,
    panache_used: &mut bool,
) -> Vec<Inline> {
    if let Some((start, end, target_start, target_end)) = sphinx_reference(text) {
        let mut inlines = parse_piece(&text[..start], offset, diagnostics, panache_used);
        let payload = &text[target_start..target_end];
        let span = SourceSpan {
            start: offset + start,
            end: offset + end,
        };
        let target_span = SourceSpan {
            start: offset + target_start,
            end: offset + target_end,
        };
        if text[start..].starts_with(":func:`") && !payload.starts_with('~') {
            inlines.push(Inline::SemanticReference {
                target: payload.into(),
                span,
                target_span,
            });
        } else {
            let target = payload.trim_start_matches('~');
            let label = if payload.starts_with('~') {
                target.rsplit('.').next().unwrap_or(target)
            } else {
                target
            };
            inlines.push(Inline::Link {
                target: format!("@ref {target}"),
                inlines: vec![Inline::Code {
                    value: label.into(),
                    span: target_span,
                }],
                title: None,
                attributes: Attributes::default(),
                span,
            });
        }
        inlines.extend(parse_piece(
            &text[end..],
            offset + end,
            diagnostics,
            panache_used,
        ));
        return inlines;
    }
    // Markdown interprets a reST role's payload as ordinary inline code,
    // which would silently discard its distinct reference semantics.
    if text.trim_start().starts_with(".. ") || has_rst_role(text) {
        return unsupported(text, offset, diagnostics);
    }
    *panache_used = true;
    let parsed = parse_authored_document(text, AuthoredFormat::Gfm);
    for mut diagnostic in parsed.diagnostics {
        diagnostic.code = DiagnosticCode::PythonUnsupportedDocstring;
        if let Some(span) = &mut diagnostic.span {
            shift(span, offset);
        }
        for span in &mut diagnostic.related_spans {
            shift(span, offset);
        }
        diagnostics.push(diagnostic);
    }
    if let [Block::Paragraph { inlines, .. }] = parsed.document.blocks.as_slice() {
        let mut inlines = inlines.clone();
        for inline in &mut inlines {
            shift_inline(inline, offset);
        }
        return inlines;
    }
    unsupported(text, offset, diagnostics)
}

fn parse_piece(
    text: &str,
    offset: usize,
    diagnostics: &mut Vec<Diagnostic>,
    panache_used: &mut bool,
) -> Vec<Inline> {
    // Parsing fragments independently would otherwise discard the spaces that
    // separate a semantic reference from the surrounding prose.
    let start = text.len() - text.trim_start().len();
    let end = text.trim_end().len().max(start);
    let mut inlines = Vec::new();
    if start > 0 {
        inlines.push(Inline::Text {
            value: text[..start].into(),
            span: SourceSpan {
                start: offset,
                end: offset + start,
            },
        });
    }
    if end > start {
        inlines.extend(parse_line(
            &text[start..end],
            offset + start,
            diagnostics,
            panache_used,
        ));
    }
    if end < text.len() {
        inlines.push(Inline::Text {
            value: text[end..].into(),
            span: SourceSpan {
                start: offset + end,
                end: offset + text.len(),
            },
        });
    }
    inlines
}

fn sphinx_reference(text: &str) -> Option<(usize, usize, usize, usize)> {
    let bytes = text.as_bytes();
    let mut index = 0;
    while index < bytes.len() {
        if bytes[index] == b'`' {
            let width = bytes[index..].iter().take_while(|b| **b == b'`').count();
            let delimiter = &text[index..index + width];
            index = text[index + width..]
                .find(delimiter)
                .map_or(bytes.len(), |end| index + width + end + width);
            continue;
        }
        if bytes[index] == b':' {
            let prefix = ["func", "class", "meth", "attr", "data", "exc", "mod", "obj"]
                .into_iter()
                .flat_map(|role| [format!(":{role}:`"), format!(":py:{role}:`")])
                .find(|prefix| text[index..].starts_with(prefix));
            let Some(prefix) = prefix else {
                index += 1;
                continue;
            };
            let start = index + prefix.len();
            if let Some(length) = text[start..].find('`') {
                let end = start + length;
                let target = &text[start..end];
                if !target.is_empty()
                    && target
                        .chars()
                        .all(|c| c.is_alphanumeric() || matches!(c, '_' | '.' | ':' | '~'))
                {
                    return Some((index, end + 1, start, end));
                }
            }
        }
        index += if bytes[index] == b'\\' { 2 } else { 1 };
    }
    None
}

fn has_rst_role(text: &str) -> bool {
    let bytes = text.as_bytes();
    let mut index = 0;
    while index < bytes.len() {
        if bytes[index] == b'`' {
            let length = bytes[index..].iter().take_while(|b| **b == b'`').count();
            let delimiter = &text[index..index + length];
            let tail = &text[index + length..];
            index = tail
                .find(delimiter)
                .map_or(bytes.len(), |end| index + length + end + length);
            continue;
        }
        if bytes[index] == b':' {
            let tail = &text[index + 1..];
            let length = tail
                .bytes()
                .take_while(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b':' | b'-'))
                .count();
            if length > 1 && tail[..length].ends_with(':') && tail[length..].starts_with('`') {
                return true;
            }
        }
        index += if bytes[index] == b'\\' { 2 } else { 1 };
    }
    false
}

fn unsupported(text: &str, offset: usize, diagnostics: &mut Vec<Diagnostic>) -> Vec<Inline> {
    let range = SourceSpan {
        start: offset,
        end: offset + text.len(),
    };
    let mut diagnostic = Diagnostic::new(
        DiagnosticCode::PythonUnsupportedDocstring,
        Severity::Warning,
        "unsupported docstring prose markup; source retained",
    );
    diagnostic.span = Some(range);
    diagnostics.push(diagnostic);
    vec![Inline::Unsupported {
        source_kind: "numpy-prose".into(),
        raw: text.into(),
        span: range,
    }]
}

fn shift(span: &mut SourceSpan, offset: usize) {
    span.start += offset;
    span.end += offset;
}

fn shift_attributes(attributes: &mut Attributes, offset: usize) {
    if let Some(id) = &mut attributes.identifier {
        shift(&mut id.span, offset);
    }
    for class in &mut attributes.classes {
        shift(&mut class.span, offset);
    }
    for pair in &mut attributes.key_values {
        shift(&mut pair.key.span, offset);
        shift(&mut pair.value.span, offset);
    }
}

fn shift_inline(inline: &mut Inline, offset: usize) {
    match inline {
        Inline::Math { span, .. }
        | Inline::Text { span, .. }
        | Inline::Space { span }
        | Inline::SoftBreak { span }
        | Inline::HardBreak { span }
        | Inline::NonbreakingSpace { span }
        | Inline::Code { span, .. }
        | Inline::AutoLink { span, .. }
        | Inline::Unsupported { span, .. } => shift(span, offset),
        Inline::Emphasis { inlines, span }
        | Inline::Strong { inlines, span }
        | Inline::Styled { inlines, span, .. }
        | Inline::Citation { inlines, span, .. }
        | Inline::Strikeout { inlines, span } => {
            shift(span, offset);
            for inline in inlines {
                shift_inline(inline, offset);
            }
        }
        Inline::Link {
            inlines,
            attributes,
            span,
            ..
        } => {
            shift(span, offset);
            shift_attributes(attributes, offset);
            for inline in inlines {
                shift_inline(inline, offset);
            }
        }
        Inline::Image {
            alt,
            attributes,
            span,
            ..
        } => {
            shift(span, offset);
            shift_attributes(attributes, offset);
            for inline in alt {
                shift_inline(inline, offset);
            }
        }
        Inline::SemanticReference {
            span, target_span, ..
        } => {
            shift(span, offset);
            shift(target_span, offset);
        }
    }
}