Class: DocsKit::Snapshot

Inherits:
Object
  • Object
show all
Defined in:
lib/docs_kit/snapshot.rb,
lib/docs_kit/snapshot/entry.rb

Overview

Reads a committed Markdown snapshot of one documentation version back as the registry duck type the rest of the kit already speaks (#all / #from_slug / #nav_items), so an archived version renders through TODAY's chrome — only the content is frozen.

A snapshot lives at <config.snapshots_path>//: a manifest.json describing the nav structure (see the schema in the snapshot task) plus one .md file per page, written by the host-run bin/rails docs_kit:snapshot[id] task at release time.

A missing directory or unreadable manifest degrades to an EMPTY snapshot (no pages) — a version configured before its snapshot is written must never take the site down. The install generator's --sync report warns about the drift instead.

Defined Under Namespace

Classes: Entry

Constant Summary collapse

SCHEMA =

The manifest format this reader understands; the writer stamps it so a future format change is detectable rather than silently misread.

1

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(version:, root:) ⇒ Snapshot

Returns a new instance of Snapshot.



73
74
75
76
77
 
# File 'lib/docs_kit/snapshot.rb', line 73

def initialize(version:, root:)
  @version = version
  @root = root
  @manifest = read_manifest
end

Instance Attribute Details

#root ⇒ Object (readonly)

Returns the value of attribute root.



71
72
73
 
# File 'lib/docs_kit/snapshot.rb', line 71

def root
  @root
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



71
72
73
 
# File 'lib/docs_kit/snapshot.rb', line 71

def version
  @version
end

Class Method Details

.for(version, config: DocsKit.configuration) ⇒ Object

The snapshot for this version, memoized per [version id, directory] and invalidated when manifest.json's mtime changes — the same reload-on-change posture as Configuration#openapi_document, so editing a snapshot in development is picked up without a server restart.



31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/docs_kit/snapshot.rb', line 31

def for(version, config: DocsKit.configuration)
  version = DocVersion.from(version)
  root = root_for(version, config)
  mtime = manifest_mtime(root)
  key = [version.id.to_s, root.to_s]

  @cache ||= {}
  cached = @cache[key]
  return cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime

  new(version: version, root: root).tap do |snapshot|
    @cache[key] = { snapshot: snapshot, mtime: mtime }
  end
end

.reset_cache! ⇒ Object 



46
47
48
 
# File 'lib/docs_kit/snapshot.rb', line 46

def reset_cache!
  @cache = {}
end

Instance Method Details

#all ⇒ Object

Every snapshot page across the manifest's registries, in manifest order — each a Snapshot::Entry quacking like a Registry::Entry.



81
82
83
 
# File 'lib/docs_kit/snapshot.rb', line 81

def all
  registries.flat_map { |registry| registry.fetch(:entries) }
end

#from_slug(slug) ⇒ Object 



85
86
87
 
# File 'lib/docs_kit/snapshot.rb', line 85

def from_slug(slug)
  all.find { |entry| entry.slug.to_s == slug.to_s }
end

#markdown_for(slug) ⇒ Object

The raw Markdown body of the page with this slug, or nil when unknown.



112
113
114
 
# File 'lib/docs_kit/snapshot.rb', line 112

def markdown_for(slug)
  from_slug(slug)&.markdown
end

#nav_groups ⇒ Object

{ heading => { group => [NavItem] } }, the Configuration#nav_groups shape, from the manifest's per-registry headings — a heading with no pages is dropped so the sidebar never shows an empty group.



99
100
101
102
103
104
 
# File 'lib/docs_kit/snapshot.rb', line 99

def nav_groups
  registries.each_with_object({}) do |registry, acc|
    items = nav_items_for(registry.fetch(:entries))
    acc[registry.fetch(:heading)] = items unless items.empty?
  end
end

#nav_items ⇒ Object

{ group => [NavItem] }, the Registry.nav_items shape — hrefs already carry the version prefix, so the Sidebar's strict path == href active-matching works unchanged.



92
93
94
 
# File 'lib/docs_kit/snapshot.rb', line 92

def nav_items
  nav_items_for(all)
end

#path_prefix ⇒ Object

The version-prefixed docs prefix (e.g. "/1.0/docs").



107
108
109
 
# File 'lib/docs_kit/snapshot.rb', line 107

def path_prefix
  "#{version.path_prefix}/docs"
end