{% extends "base.html" %} {% from "layout/icons.html" import icon %} {% block title %}{{ _("Documentation") }}{% endblock %} {% block content %} {# A list of `listed` items and its folded rest; with a filter, each item carries its kind and the rest's summary is written once per kind, so the chips can show the right count without the script translating anything. #} {% macro listing(items, filter=none) -%} {% if items|length > listed %}
{% if filter %}{% for kind, count in filter.folded.items() %}{% trans count=count %}{{ count }} more{% endtrans %}{% endfor %}{% else %}{% trans count=items|length - listed %}{{ count }} more{% endtrans %}{% endif %}
{% endif %} {%- endmacro %} {# Chips only when the list holds two kinds or more: with one, a chip would show what All shows. #} {% macro chips(filter, names) -%} {% if filter.totals|length > 2 %}

{% endif %} {%- endmacro %} {# A stacked bar with its legend; parts are (tone, count, name), and the bar's text alternative names each count. #} {% macro stack(parts) -%} {%- endmacro %} {# A tile's small bar: the tile already says its numbers in words. #} {% macro mini(parts) -%} {%- endmacro %} {% macro hbar(label, count, widest, value, tone="series-fill-1") -%}
  • {{ label }}{{ value }}
  • {%- endmacro %} {% macro page_bar(row, widest) -%} {% set documented = row.documented / widest * 100 %}
  • {{ row.page.title }}{{ row.documented }} / {{ row.inferred }}
  • {%- endmacro %} {% macro fact_link(entity) -%} {{ entity.id }} {%- endmacro %} {% macro decision_link(decision) -%} {{ decision.attributes.get("number", "") }} · {{ decision.attributes.get("title", "") }}{% if decision.attributes.get("date") %}{{ decision.attributes.date }}{% endif %} {%- endmacro %} {% macro share(value) -%} {% if value.denominator %}{% trans numerator=value.numerator, denominator=value.denominator %}{{ numerator }} of {{ denominator }}{% endtrans %}{% else %}{{ _("nothing to measure yet") }}{% endif %} {%- endmacro %} {% macro about(text) -%}
    {{ _("What this counts") }}

    {{ text }}

    {%- endmacro %} {% macro tile_card(tile, label, title_id, parts=none) %}
    {{ label }} {% if tile.value is none %} —{{ _("Not available just now.") }} {% elif tile.metric == "adr_attention" %} {{ tile.value.numerator }} {{ _("proposed too long, or retired and still cited") }} {% elif tile.metric == "documented_share" and not tile.value.denominator %} —{{ _("No pages yet: the guide's rationale is measured once your assistant writes it.") }} {% else %} {% if tile.percent is not none %}{{ tile.percent }}%{% else %}—{% endif %} {{ share(tile.value) }} {% if parts %}{{ mini(parts) }}{% endif %} {% endif %} {% if tile.value is not none and (tile.value.denominator or tile.metric == "adr_attention") %} {% if tile.change is none %}{{ _("No earlier update to compare with.") }}{% elif tile.metric == "adr_attention" %}{% trans change="%+d"|format(tile.change) %}{{ change }} since the last update{% endtrans %}{% else %}{% trans change="%+d"|format(tile.change) %}{{ change }} points since the last update{% endtrans %}{% endif %} {% endif %} {% if tile.points %} {% set count = tile.trend_text.split(", ")|length %} {% endif %}
    {% endmacro %}

    {{ _("Documentation") }}

    {{ _("How well the repository explains itself: its guide's rationale, its commits, its decisions and its documents. Measured from the code and the guide, without calling your assistant.") }}

    {% if report is none %}
    {% if unavailable %}

    {{ _("The metrics aren't available just now") }}

    {{ _("Codetrail couldn't read the target's data; the log says why.") }}

    {% else %}

    {{ _("No facts yet") }}

    {{ _("Update the guide once: reading the code is free, and the metrics come from it.") }}

    {% endif %}
    {% else %} {% set rationale, commits, decisions = report.rationale, report.commits, report.decisions %} {% set mentions, explained, has_pages = report.mentions, report.explained, report.rationale.pages %}

    {{ icon("chevron") }}{{ _("Documented rationale") }}

    {% if not has_pages %}{{ _("No pages yet") }}{% elif rationale.inferred %}{% trans count=rationale.inferred %}{{ count }} inferred, worth documenting{% pluralize %}{{ count }} inferred, worth documenting{% endtrans %}{% else %}{{ _("Nothing inferred") }}{% endif %}
    {{ about(_("Rationale blocks in the guide's area and concept pages: documented ones quote a source Codetrail checked, inferred ones are the assistant's reading. It counts only what the guide wrote about.")) }} {% if not has_pages %}

    {{ _("No pages yet: the guide's rationale is measured once your assistant writes it.") }}

    {% else %} {{ stack([("heat-4", rationale.by_source.adr, _("ADRs")), ("heat-3", rationale.by_source.docs, _("Documents")), ("heat-2", rationale.by_source.code, _("Code comments")), ("heat-1", rationale.by_source.commit, _("Commit messages")), ("tone-inferred", rationale.inferred, _("Inferred"))]) }}

    {{ _("By page, most inferred first") }}

    {% set ns = namespace(widest=1) %}{% for row in rationale.pages %}{% set ns.widest = [ns.widest, row.documented + row.inferred]|max %}{% endfor %}
      {% for row in rationale.pages[:listed] %}{{ page_bar(row, ns.widest) }}{% endfor %}
    {% if rationale.pages|length > listed %}
    {% trans count=rationale.pages|length - listed %}{{ count }} more{% endtrans %}
      {% for row in rationale.pages[listed:] %}{{ page_bar(row, ns.widest) }}{% endfor %}
    {% endif %} {% if rationale.inferred_blocks %}

    {{ _("Inferred: worth documenting") }}

    {% call(block) listing(rationale.inferred_blocks) %}{{ block.first_line }}{{ block.page.title }}{% endcall %} {% endif %} {% endif %}

    {{ icon("chevron") }}{{ _("Commits that explain why") }}

    {% if commits is none %}{{ _("Not available just now.") }}{% else %}{% trans count=commits.without_why|length, measured=commits.measured %}{{ count }} without a why, of the latest {{ measured }}{% pluralize %}{{ count }} without a why, of the latest {{ measured }}{% endtrans %}{% endif %}
    {% if commits is none %}

    {{ _("The commit history couldn't be read just now; the log says why.") }}

    {% else %} {{ about(_("The latest commits on the branch, merges left out. A commit explains why when its body matches the target's commit_why_pattern.")) }} {{ stack([("tone-documented", commits.explains_why, _("Explain why")), ("tone-other", commits.body_only, _("Body without a why")), ("tone-quiet", commits.subject_only, _("Subject only"))]) }} {% if commits.withheld %}

    {% trans count=commits.withheld %}{{ count }} message withheld: gitleaks flagged it{% pluralize %}{{ count }} messages withheld: gitleaks flagged them{% endtrans %}

    {% endif %} {% if commits.without_why %}

    {{ _("Without a why") }}

    {{ chips(commit_filter, [("body-only", _("Body without a why")), ("subject-only", _("Subject only"))]) }} {% call(commit) listing(commits.without_why, commit_filter) %}{{ commit.sha[:7] }}{{ commit.subject }}{% if commit.body %}{{ _("body without a why") }}{% else %}{{ _("subject only") }}{% endif %}{% endcall %}
    {% endif %} {% endif %}
    {% set to_check = decisions.undated|length + (decisions.uncited|length if has_pages else 0) %}

    {{ icon("chevron") }}{{ _("Architecture decisions") }}

    {% if not decisions.by_status %}{{ _("None found") }}{% else %}{% trans count=decisions.attention %}{{ count }} needs attention{% pluralize %}{{ count }} need attention{% endtrans %}{% if to_check %} · {% trans count=to_check %}{{ count }} to check{% pluralize %}{{ count }} to check{% endtrans %}{% endif %}{% endif %}
    {% if not decisions.by_status %}

    {{ _("No architecture decision records were found where the target's settings say they live.") }}

    {% else %} {{ about(_("A proposed ADR needs attention once it waits longer than the target's settings allow, and a superseded or deprecated one while a guide page still cites it. Worth a look: proposed ADRs with no date, and accepted ones no page cites.")) }}

    {{ _("By status") }}

    {% set widest = decisions.by_status.values()|map("length")|max %}
      {% for status, found in decisions.by_status|dictsort %}{{ hbar(status, found|length, widest, found|length|number, "series-fill-5" if status in ("superseded", "deprecated") else "series-fill-1") }}{% endfor %}
    {% if decisions.overdue or decisions.superseded_cited %}

    {{ _("Needs attention") }}

    {% if decisions.overdue %}

    {{ _("Proposed for too long") }}

    {% call(decision) listing(decisions.overdue) %}{{ decision_link(decision) }}{% trans count=days_proposed(decision, today) %}proposed {{ count }} day ago{% pluralize %}proposed {{ count }} days ago{% endtrans %}{% endcall %} {% endif %} {% if decisions.superseded_cited %}

    {{ _("Superseded or deprecated, still cited by the guide") }}

    {% call(decision) listing(decisions.superseded_cited) %}{{ decision_link(decision) }}{% endcall %} {% endif %} {% endif %} {% if to_check %}

    {{ _("Worth a look") }}

    {% if decisions.undated %}

    {{ _("Proposed, with no date") }}

    {% call(decision) listing(decisions.undated) %}{{ decision_link(decision) }}{% endcall %} {% endif %} {% if decisions.uncited and has_pages %}

    {{ _("Accepted, but no page cites them") }}

    {% call(decision) listing(decisions.uncited) %}{{ decision_link(decision) }}{% endcall %} {% endif %} {% endif %}
    {% endif %}
    {% set mention_total = mentions.mentioned|length + mentions.unmentioned|length %}

    {{ icon("chevron") }}{{ _("Mentioned and explained") }}

    {% trans count=mentions.unmentioned|length %}{{ count }} never mentioned{% pluralize %}{{ count }} never mentioned{% endtrans %}{% if has_pages %} · {% trans count=explained.unexplained|length %}{{ count }} unexplained{% pluralize %}{{ count }} unexplained{% endtrans %}{% endif %}
    {{ about(_("A package counts when a document names it as a whole word, a project when its folder holds a README or a document names its folder, and a resource when a document names its address. A fact is explained when it falls in the scope of a written area or concept page.")) }}

    {{ _("External packages, projects and infrastructure resources that some document names. A mention isn't a reason: this only shows what no document talks about at all.") }}

      {% set value %}{% trans numerator=mentions.mentioned|length, denominator=mention_total %}{{ numerator }} of {{ denominator }}{% endtrans %}{% endset %} {{ hbar(_("Mentioned in a document"), mentions.mentioned|length, mention_total, value) }} {% if has_pages %} {% set value %}{% trans numerator=explained.explained, denominator=explained.total %}{{ numerator }} of {{ denominator }}{% endtrans %}{% endset %} {{ hbar(_("Explained by a guide page"), explained.explained, explained.total, value) }} {% endif %}
    {% if not has_pages %}

    {{ _("Which facts the guide explains, and which ADRs it cites, are measured once your assistant has written its pages.") }}

    {% endif %}
    {% if mentions.unmentioned %}

    {{ _("Not mentioned in any document") }}

    {{ chips(fact_filter, [("package", _("Packages")), ("project", _("Projects")), ("resource", _("Resources"))]) }} {% call(entity) listing(mentions.unmentioned, fact_filter) %}{{ fact_link(entity) }}{% endcall %}
    {% endif %} {% if explained.unexplained and has_pages %}

    {{ _("Not explained by any page") }}

    {% call(entity) listing(explained.unexplained) %}{{ fact_link(entity) }}{% endcall %}
    {% endif %}
    {% endif %}
    {% endblock %}