cf-docs-rfc-proposal

Partial survey

Status: draft, incomplete — covers what is known as of 2026-10-11.

This survey counts every partial call and every partial file in the 15 cloudfoundry/docs-* repositories and in the book’s own repository, and records how each call is written, where its partial lives, and what the partial holds. A partial is a file of content that is not a page of its own and is rendered inside the pages that include it; the book names partial files _name.html.md.erb and includes them with <%= partial 'name' %>. The survey was done on 2026-10-11 to choose the test pages of the partials round and to give data to the open question whether partial names held in variables are still needed (R-05 partials and reuse; research area).

File What it is
calls.csv One row per call, 55 rows: the call as written, its form, where it sits, and the file it resolves to, each with a GitHub link to the call at the surveyed commit
partials.csv One row per partial file, 48 rows: what it holds, who includes it, how often, and whether a variable names it
shas.txt The 15 repositories and the commit surveyed in each: the notes survey’s list
shas-2026-07.txt The same list with eight repositories set to the commit before their July 2026 cleanup (see History)
survey.py Finds the calls and partial files in a set of clones and writes both CSV files
summary.py Prints the counts below from the two CSV files

Scope

How the book resolves a partial

The book pins bookbindery 9.12.1 in its Gemfile; the repository has no Gemfile.lock. (Its Docker preview pins 10.1.18 instead, docker/files/Gemfile L2, which runs Middleman 4; that path was not traced.) Bookbinder’s repository is pivotal-cf/bookbinder; cloudfoundry-incubator/bookbinder redirects to it. The 9.12.1 gem on RubyGems differs from the repository’s v9.12.0 tag (f608a44) in two files that do not touch partials (code_example_reader.rb and preprocessor.rb, a change of Ruby syntax; compared with diff on 2026-10-11), so the lines below are cited at that tag. It requires Middleman ~> 3.4.0 (gemspec), which uses padrino-helpers ~> 0.12.3 (middleman-core gemspec, v3.4.1). Middleman 3.4.1 and padrino-helpers 0.12.9 are the newest releases those requirements allow; which patch release the book’s build installs is not recorded anywhere found.

  1. The site’s source tree. Bookbinder copies its own master_middleman/ into the output, then the book’s over it (directory_preparer.rb L16-L17, layout_preparer.rb L21). Each section’s repository is then linked into master_middleman/source/ under the section’s directory: from the book’s config.yml (link_to_site_gen_dir.rb L17-L22, destination_directory.rb L4-L12; config.yml L8-L13). So docs-cf-admin is adminguide/, docs-dev-guide devguide/, and so on: all repositories share one source tree.
  2. dependent_sections bring no partials. A dependent section is cloned under its parent’s folder unless it is marked no_docs (section_repository.rb L20-L30). All six dependent sections in the book’s config.yml are no_docs: true (sample-app and release repositories), so none adds content or partials.
  3. The name. partial 'a/b' asks for a/_b: padrino-helpers puts an underscore before the last path segment (render_helpers.rb L33-L38, 0.12.9). The same helper takes locals:.
  4. The lookup. Middleman looks for that path first relative to the calling file’s folder, then from the source root, and then under the partials_dir setting, which is empty by default (rendering.rb L202-L212, L237-L252, application.rb L133). Each try accepts any template extension and also the file name without its leading underscore; a leading / is dropped, so /x/y is read from the source root (L476-L515). A partial in another repository is therefore reached through the other section’s folder: /<directory>/name or ../<directory>/name.
  5. Missing partials. Middleman raises “Could not locate partial” (L212); its build records the error, goes on, and exits with status 1 (cli/build.rb L74-L82).
  6. Two passes. A partial is rendered through all its own extensions (.erb, then .md) before the host page’s Markdown reads the result (rendering.rb L169-L191). The host’s Markdown therefore sees HTML where the call was. The published pages show the effect: in a list item after a label, the partial’s paragraph becomes a <p> inside the item’s <p> (published architecture, line 586); and the last paragraph of _tcp_modify_ports, indented under its step in the partial, is published after the list (published enabling-tcp-routing, line 628).
  7. The quick links leave partials out. The “On this page” list is made from the page’s own source file (bookbinder_helpers.rb L110-L114), so headings that a partial holds are not in it: using-vol-services, whose 17 headings are all in its partial, has an empty list (published copy, line 515; browser check).
  8. Bookbinder’s own partials. The layout’s subnav comes from partial "subnavs/#{subnav_template_name}", the subnav_template of the page’s section (bookbinder_helpers.rb L46-L48): the book’s _cf-subnav.erb.

Method

survey.py reads every file and finds three forms:

Form What is found
erb an ERB tag (<%=, <%-, <%) whose code starts with partial, render or render_partial
comment an ERB comment (<%# … %>) that mentions a partial; counted, not resolved
snippet a pymdownx.snippets line, --8<-- "path" (docs-bosh only)

For each ERB call it records the tag, the quotes, how the name is given (a literal, a variable such as vars.x, a string with #{…}, or another expression), the path style (a bare name, ./, ../, a folder, or a leading /), locals:, whether the call sits inside an ERB if, unless, case or block, and where it sits: at the top level, in a Markdown list item (on the item’s first line, after text on that line, or indented under it), inside an HTML <li> or table cell, inside other HTML, after text, or in a fenced code block. It then resolves the name the way Middleman does (above) in a model of the book’s source tree, built from the book’s config.yml, and records where the partial lives: in the same folder, another folder of the same repository, another repository, the book repository, or the Bookbinder gem (with the gem unpacked, the fifth argument); or that it is missing.

For each partial file (a file whose name starts with _, or any file a call resolves to) it records its headings (Markdown # outside fences, and HTML <h1>–<h6>), explicit ids (<a id>), notes, tables, code blocks, variables, partial calls and other ERB; front matter; how often and from which files it is included; whether it is included twice on one page or from another repository; how deep it nests; and the variables whose value names it, and whether any page uses them.

Totals

  Calls Files with calls Partial files
Content repositories (14) 45 24 44
Book repository 7 (in layouts/layout.erb) 1 4
bosh.io (docs-bosh), snippets 2 1 —

The 45 content calls: docs-cloudfoundry-concepts 12, docs-cf-admin 10, docs-dev-guide 10, docs-running-cf 8, docs-loggregator 4, docs-credhub 1. docs-bbr, docs-buildpacks, docs-cf-cli, docs-deploying-cf, docs-services, docs-uaa and docs-dotnet-core-tutorial have none. One more ERB comment mentions a partial (overview L216).

Findings

Call forms. Every call is <%= partial '…' %> with a literal name: 37 in single quotes, 8 in double quotes. None uses <%-, render, locals:, a variable or interpolation for the name, and none sits inside a conditional. 35 give a bare name, 9 start with ./ (the eight ./metrics/… calls in all_metrics and ./oss_credhub), and one goes up through the section’s own folder, ../adminguide/tcp_modify_ports (enabling-tcp-routing L88), which works only because the book names docs-cf-admin’s folder adminguide.

Where partials live. 37 calls find their partial in the caller’s folder and 8 in a subfolder of the same repository (metrics/). No call reaches another repository, the book repository, or a missing file. The book’s layout includes 3 partials of its own and 4 that only the Bookbinder gem provides (layouts/header, local-header, title, page-footer).

Where calls sit. 41 are on a line of their own at the top level. Four are in Markdown list items: three after a bold label, * **Log Cache:** <%= partial 'log_cache' %> (architecture L59, L83, L89), and one as the whole of a step, 1. <%= partial "…" %> (enabling-tcp-routing L88). None sits in HTML or in a table cell.

What partials hold (44 partial files in the content repositories): tables 15, code blocks 14, explicit ids 11, headings 9, variables 8, notes 3. The nine with headings are listed by summary.py; the largest is _using-vol-services, 17 headings h2–h4, every one with an <a id>. No partial calls another partial, holds other ERB, or has front matter: nesting depth is 0.

Reuse. 40 partial files are included from one file, one from two (_routing_conflict, from routes-domains L406 and troubleshoot-app-health L148), and three from none: _gorouter_client_cert_oss, _overview and _spare-cpu-and-throttling. Two partials are included more than once on one page: _v3-note, three times on manifest-attributes, and _log_cache, twice on architecture. Neither holds a heading or an id, so neither makes an id twice today. The book’s _cf-subnav.erb is included by Bookbinder’s helper, not by a call.

A page that is only a partial call. using-vol-services is front matter and <%= partial 'using-vol-services' %>; it is the only such page.

bosh.io. docs-bosh includes two SVG diagrams with --8<-- "snippets/diagrams/…" (changing-deployment-vm-strategy L10, L14), through pymdownx.snippets, which its mkdocs.yml turns on (L385). It has no other include.

Partial names held in variables

Ten values in template_variables.yml name a partial file of a content repository, and no page uses any of them:

Variable Value Partial Line
concepts_product_model_text "./overview_model" _overview_model (concepts) L88
roles_table "_oss_roles_table" _oss_roles_table (concepts) L231
scale_table "oss_scale_table" _oss_scale_table (concepts) L287
suspended_roles_table "_suspended_org_roles_table" _suspended_org_roles_table (concepts) L301
tcp_port "../adminguide/tcp_modify_ports" _tcp_modify_ports (cf-admin) L305
zipkin_enable zipkin_oss_config _zipkin_oss_config (cf-admin) L314
gorouter_client_cert "gorouter_client_cert_oss" _gorouter_client_cert_oss (cf-admin) L344
ssl_termin_gorouter "ssl_termin_gorouter_oss" _ssl_termin_gorouter_oss (cf-admin) L345
ssl_termin_lb_only "ssl_termin_lb_only_oss" _ssl_termin_lb_only_oss (cf-admin) L346
ssl_termin_gorouter_lb "ssl_termin_gorouter_lb_oss" _ssl_termin_gorouter_lb_oss (cf-admin) L347

The pages that include these partials name them directly, for example high-availability L102, <%= partial 'oss_scale_table' %>. The only remaining mention is an ERB comment, <%# partials for vars.concepts_product_model_text %> (overview L216).

History

The commits below are in the public repositories’ history; their messages are quoted.

So the mechanism the variables served, one source rendering a different partial in each edition’s book, has had no user since August 2024, and the second edition it chose for left the repositories in July 2026.

How to rerun

Run from a working directory outside this repository, with python3 -I. SURVEY stands for this folder, concepts/partials/survey. Each repository is fetched at its commit, without history:

mkdir -p repos
git init -q repos/docs-bbr
git -C repos/docs-bbr fetch -q --depth 1 https://github.com/cloudfoundry/docs-bbr.git 51465950ce3a2196d66a9339086b94feed280c3e
git -C repos/docs-bbr checkout -q FETCH_HEAD
# … the same three lines for each repository in SURVEY/shas.txt

# The bookbindery 9.12.1 gem, unpacked (for the layout partials it provides)
mkdir -p gem && curl -fsSL -o gem/bb.gem https://rubygems.org/downloads/bookbindery-9.12.1.gem
tar -xf gem/bb.gem -C gem && mkdir gem/src && tar -xzf gem/data.tar.gz -C gem/src

python3 -I SURVEY/survey.py repos SURVEY/shas.txt calls.csv partials.csv gem/src
cmp calls.csv SURVEY/calls.csv && cmp partials.csv SURVEY/partials.csv
python3 -I SURVEY/summary.py SURVEY/calls.csv SURVEY/partials.csv

For the History counts, fetch the eight repositories at the commits in shas-2026-07.txt into another folder (the others as above) and run survey.py and summary.py on it. The scripts read files only; they run nothing from the clones or the gem.