diplodocus 0.15.0

Build coherent documentation websites for polyglot software projects.
Documentation
mod support;

use diplodocus::assembly::assemble_workspace;
use diplodocus::rendering::{render_fragments, render_site};
use diplodocus::site::Site;
use diplodocus::snapshots::Snapshot;
use diplodocus::validation::{resolve_item, resolve_workspace};

fn route(item: &diplodocus::ir::ItemReference) -> String {
    format!(
        "packages/python/reference/{}.html",
        diplodocus::provenance::fingerprint_bytes(item.item.as_bytes()).value
    )
}

fn member_anchor(item: &diplodocus::ir::ItemReference) -> String {
    item.item.rsplit('.').next().unwrap().to_owned()
}

#[test]
fn class_pages_contain_fields_methods_and_inherited_links() {
    let root = support::TestWorkspace::from_fixture("python-overloads");
    root.write(
        "python/demo/_api.py",
        r#"
from dataclasses import dataclass, field
from typing import Generic, TypeVar, overload
T = TypeVar("T")

def target() -> None:
    """A helper target."""

@dataclass(frozen=True)
class Base(Generic[T]):
    """A fitted result."""
    size: int
    names: list[str] = field(default_factory=list)
    disabled: bool = field(default=False, init=False)

    @overload
    def draw(self, value: str) -> str: ...
    @overload
    def draw(self, value: bytes) -> bytes: ...
    def draw(self, value: str | bytes) -> str | bytes:
        """Draw a result using :func:`demo.target`.

        Parameters
        ----------
        value:
            The complete drawing input.
        """
        return value

class Child(Base[int]):
    """A specialized result."""

class Override(Base[int]):
    """A customized result."""
    def draw(self, value: int) -> int:
        """Draw the customized result."""
        return value

class Left(Base[int]):
    """An unchanged branch."""

class Right(Base[int]):
    """A changed branch."""
    def draw(self, value: int) -> int:
        """Draw from the right branch."""
        return value

class Diamond(Left, Right):
    """A diamond inheritance example."""
"#,
    );
    root.write("python/demo/__init__.py", "from ._api import Base, Child, Diamond, Left, Override, Right, target\n__all__ = ['Base', 'Child', 'Diamond', 'Left', 'Override', 'Right', 'target']\n");
    let sources = assemble_workspace(root.path().join("diplodocus.yaml")).unwrap();
    let snapshot = Snapshot::from_sources(&sources, &resolve_workspace(&sources).unwrap()).unwrap();
    let site = Site::new(&snapshot).unwrap();
    let rendered = render_site(&site).unwrap();
    let fragments = render_fragments(&site).unwrap();
    let workspace = snapshot.workspace();
    let base = resolve_item(workspace, Some("python"), "demo.Base").unwrap();
    let child = resolve_item(workspace, Some("python"), "demo.Child").unwrap();
    let override_class = resolve_item(workspace, Some("python"), "demo.Override").unwrap();
    let draw = resolve_item(workspace, Some("python"), "demo.Base.draw").unwrap();
    let size = resolve_item(workspace, Some("python"), "demo.Base.size").unwrap();
    let html = std::str::from_utf8(&rendered.files()[&route(&base)].bytes).unwrap();
    assert!(html.contains("id=\""));
    assert!(html.contains(&format!("id=\"{}\"", member_anchor(&draw))));
    assert!(html.contains(&format!("id=\"{}\"", member_anchor(&size))));
    assert!(html.contains("The complete drawing input."));
    assert!(html.contains("<h3>Parameters</h3>"));
    assert!(html.contains(">demo.target()</code></a>"));
    assert!(!rendered.files().contains_key(&route(&draw)));
    let child_html = std::str::from_utf8(&rendered.files()[&route(&child)].bytes).unwrap();
    let base_filename = route(&base).rsplit('/').next().unwrap().to_owned();
    assert!(child_html.contains("Constructor inherited from"));
    assert!(child_html.contains(&format!("{base_filename}#{}", member_anchor(&draw))));
    assert!(child_html.contains(&format!("{base_filename}#{}", member_anchor(&size))));
    let override_html =
        std::str::from_utf8(&rendered.files()[&route(&override_class)].bytes).unwrap();
    assert!(override_html.contains("Draw the customized result."));
    assert!(!override_html.contains(&format!("{base_filename}#{}", member_anchor(&draw))));
    let diamond = resolve_item(workspace, Some("python"), "demo.Diamond").unwrap();
    let right = resolve_item(workspace, Some("python"), "demo.Right").unwrap();
    let diamond_html = std::str::from_utf8(&rendered.files()[&route(&diamond)].bytes).unwrap();
    assert!(diamond_html.contains(&format!(
        "{}#draw",
        route(&right).rsplit('/').next().unwrap()
    )));
    assert!(!diamond_html.contains(&format!("{base_filename}#draw")));
    let search: Vec<serde_json::Value> =
        serde_json::from_slice(&rendered.files()["assets/search.json"].bytes).unwrap();
    assert!(
        !search
            .iter()
            .any(|entry| entry["title"] == "demo.Base.draw")
    );
    assert!(
        search
            .iter()
            .find(|entry| entry["title"] == "demo.Base")
            .unwrap()["text"]
            .as_str()
            .unwrap()
            .contains("The complete drawing input.")
    );
    let documents: serde_json::Value =
        serde_json::from_slice(&fragments.files()["documents.json"].bytes).unwrap();
    assert!(
        documents["documents"]
            .as_array()
            .unwrap()
            .iter()
            .find(|document| document["path"] == route(&base))
            .unwrap()["identities"]
            .as_array()
            .unwrap()
            .len()
            > 1
    );

    let text = code_text(html);
    assert!(
        text.contains("Base(size: int, names: list[str] = <factory>)"),
        "{text}"
    );
    assert!(text.contains("draw(value: str) -> str"), "{text}");
    assert!(text.contains("draw(value: bytes) -> bytes"), "{text}");
    let markdown_route = route(&base).replace(".html", ".md");
    let markdown = std::str::from_utf8(&fragments.files()[&markdown_route].bytes).unwrap();
    assert!(markdown.contains("<a id=\"draw\"></a>"));
    assert!(markdown.contains("<a id=\"constructor\"></a>"));
    assert!(markdown.contains("Base(size: int, names: list[str] = <factory>)"));
    assert!(markdown.contains("draw(value: str) -> str"));
    assert!(markdown.contains("draw(value: bytes) -> bytes"));
    assert!(markdown.contains("The complete drawing input."));
    assert!(markdown.contains("### Parameters"));
}

#[test]
fn explicit_constructors_and_inherited_bases_remain_bounded() {
    let root = support::TestWorkspace::from_fixture("python-overloads");
    root.write(
        "python/pyproject.toml",
        "[project]\nname = 'overload-demo'\nversion = '0.1.0'\nrequires-python = '>=3.11'\n",
    );
    root.write(
        "python/demo/_api.py",
        r#"
class Plain:
    """A plain class."""
    def __init__(self, size: int, /, *, enabled: bool = True) -> None:
        """Initialize the complete configuration."""

class Derived(Plain):
    """An inherited initializer."""

class First:
    """A runtime class with an annotated field."""
    count: int

class Second(First):
    """A derived runtime class."""
    label: str

class NativeError(ValueError):
    """A native error surfaced through a maintained stub."""
"#,
    );
    root.write("python/demo/__init__.py", "from ._api import Plain, Derived, First, Second, NativeError\n__all__ = ['Plain', 'Derived', 'First', 'Second', 'NativeError']\n");
    let sources = assemble_workspace(root.path().join("diplodocus.yaml")).unwrap();
    let snapshot = Snapshot::from_sources(&sources, &resolve_workspace(&sources).unwrap()).unwrap();
    let rendered = render_site(&Site::new(&snapshot).unwrap()).unwrap();
    let plain = resolve_item(snapshot.workspace(), Some("python"), "demo.Plain").unwrap();
    let derived = resolve_item(snapshot.workspace(), Some("python"), "demo.Derived").unwrap();
    let plain_html = std::str::from_utf8(&rendered.files()[&route(&plain)].bytes).unwrap();
    assert!(code_text(plain_html).contains("Plain(size: int, /, *, enabled: bool = True)"));
    assert!(plain_html.contains("Initialize the complete configuration."));
    assert!(plain_html.contains("id=\"__init__\""));
    let derived_html = std::str::from_utf8(&rendered.files()[&route(&derived)].bytes).unwrap();
    assert!(code_text(derived_html).contains("Derived(size: int, /, *, enabled: bool = True)"));
    assert!(derived_html.contains("Constructor inherited from"));
    let error = resolve_item(snapshot.workspace(), Some("python"), "demo.NativeError").unwrap();
    let error_html = std::str::from_utf8(&rendered.files()[&route(&error)].bytes).unwrap();
    assert!(code_text(error_html).contains("ValueError"));
    for name in ["demo.First", "demo.Second"] {
        let item = resolve_item(snapshot.workspace(), Some("python"), name).unwrap();
        assert!(rendered.files().contains_key(&route(&item)));
    }
}

#[test]
fn nested_classes_keep_their_own_page_and_method_anchors() {
    let root = support::TestWorkspace::from_fixture("python-overloads");
    root.write(
        "python/demo/_api.py",
        r#"
class Nested:
    """An outer public class."""
    class Inner:
        """A nested public class."""
        def method(self, value: int) -> int:
            """Keep this method on the nested class page."""
            return value

def usage() -> None:
    """Use :func:`demo.Nested.Inner.method`."""
"#,
    );
    root.write(
        "python/demo/__init__.py",
        "from ._api import Nested, usage\n__all__ = ['Nested', 'usage']\n",
    );
    let sources = assemble_workspace(root.path().join("diplodocus.yaml")).unwrap();
    let snapshot = Snapshot::from_sources(&sources, &resolve_workspace(&sources).unwrap()).unwrap();
    let rendered = render_site(&Site::new(&snapshot).unwrap()).unwrap();
    let outer = resolve_item(snapshot.workspace(), Some("python"), "demo.Nested").unwrap();
    let inner = resolve_item(snapshot.workspace(), Some("python"), "demo.Nested.Inner").unwrap();
    let method = resolve_item(
        snapshot.workspace(),
        Some("python"),
        "demo.Nested.Inner.method",
    )
    .unwrap();
    let usage = resolve_item(snapshot.workspace(), Some("python"), "demo.usage").unwrap();
    let outer_html = std::str::from_utf8(&rendered.files()[&route(&outer)].bytes).unwrap();
    let inner_html = std::str::from_utf8(&rendered.files()[&route(&inner)].bytes).unwrap();
    let usage_html = std::str::from_utf8(&rendered.files()[&route(&usage)].bytes).unwrap();
    assert!(!outer_html.contains("A nested public class."));
    assert!(inner_html.contains("A nested public class."));
    assert!(inner_html.contains("id=\"method\""));
    assert!(inner_html.contains("Keep this method on the nested class page."));
    assert!(!rendered.files().contains_key(&route(&method)));
    assert!(usage_html.contains(&format!(
        "{}#method",
        route(&inner).rsplit('/').next().unwrap()
    )));
    let search: Vec<serde_json::Value> =
        serde_json::from_slice(&rendered.files()["assets/search.json"].bytes).unwrap();
    assert_eq!(
        search
            .iter()
            .filter(|entry| entry["title"] == "demo.Nested.Inner")
            .count(),
        1
    );
}

fn code_text(html: &str) -> String {
    use html5ever::tendril::TendrilSink;
    use markup5ever_rcdom::{Handle, NodeData, RcDom};
    fn text(node: &Handle) -> String {
        if let NodeData::Text { contents } = &node.data {
            return contents.borrow().to_string();
        }
        node.children.borrow().iter().map(text).collect()
    }
    let document = html5ever::parse_document(RcDom::default(), Default::default()).one(html);
    text(&document.document)
}