📜 Add inequality visualization technical documentation#5957
Draft
paarriagadap wants to merge 16 commits into
Draft
📜 Add inequality visualization technical documentation#5957paarriagadap wants to merge 16 commits into
paarriagadap wants to merge 16 commits into
Conversation
Companion document for the income-plots bespoke visualization in owid-grapher. Covers PIP 1000-binned distribution data, PPP/CPI currency conversion logic, KDE methodology, and share-below-line computation.
Contributor
Author
|
@codex review |
|
To use Codex here, create a Codex account and connect to github. |
Contributor
|
Quick links (staging server):
Login: chart-diff: ✅No charts for review.Edited: 2026-04-21 14:52:04 UTC |
Captures lessons from drafting the inequality visualization doc: canonical section structure, admonition/collapsible patterns, writing principles (lead with intuition, explain why, flag approximations), and the ai/ → docs/analyses/ → PR workflow.
Add the doc to zensical.toml under Technical publications and add a card to docs/analyses/index.md following the existing pattern. Also enhance the create-analysis-doc skill: concrete template for the landing-page card (plus extra-button patterns for notebooks, Colab, data downloads), and explicit note that nav + landing-page registration is required for the doc to appear on docs.owid.io.
Unescape markdown artefacts from Google Doc export (\!\!\! admonitions, escaped brackets and equals signs), put admonition content on its own indented line so mkdocs-material renders the callouts, indent the country list under the ??? block so it actually collapses, drop the literal ** wrapping on headings, and normalize "international dollars" to lowercase except when sentence-initial.
Adds `status: new` frontmatter so the page shows the "Recently added" badge in the docs sidebar, matching the slavery analysis.
Demote Share of population below a poverty line, Currency, Time interval, and Colors to H3 under Methodology, and their children accordingly. All four describe methodological choices and belong together in the doc outline.
Contributor
Author
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9a4681e0f4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Unescape `\!\!\!` admonitions and move their content onto an indented line so mkdocs-material renders the callouts. Indent the 218-country list under the ??? quote block so it actually collapses (was previously wrapped in a fenced code block). Drop the ** wrapping on headings, unescape `\[`, `\]`, `\.`, `\=`, `\~`, `\_`, `\)`, fold the "How accurate is this?" paragraph and cross-check into a single note, and tidy the author line.
Restructure the data-sources skeleton around "Data source: <provider>" with an optional Data processing sub-section. Rename the generic Methodology placeholder to encourage project-specific naming. Offer two Limitations layouts (flat list vs. two-tier prose+bullets). Add first-person voice and optional source-code excerpts to the style conventions. Add two conditional writing principles: pair approximations with cross-checks inside the same callout, and add "what changes / what doesn't" invariance callouts for user-facing toggles. Add parameter-sensitivity subsections to the "when to add extra H2 sections" list. Every new pattern is gated on an explicit trigger so it doesn't bloat docs without the matching concern.
Unescaped $...$ pairs in body text render as inline math under Zensical/mkdocs-material. Escape all monetary dollar signs with a backslash (\$3, \$1,000, \$0.25) in the three affected paragraphs. Code-block dollar signs are left alone since code blocks bypass markdown processing. Also record the rule in the create-analysis-doc skill so future docs apply the escape from the start.
KaTeX auto-render was pairing any two $ signs on a paragraph and rendering the content between them as italic math — which wrecks prose in a site where monetary amounts appear constantly ("between $1 and $2" became math). Drop $...$ from the delimiter list in docs/javascripts/katex.js; inline math now requires \(...\). Update the only existing inline-math use in docs/guides/demo.md to the new syntax, and unescape the \$ workaround I added earlier in the inequality viz doc since it's no longer needed. Update the create-analysis-doc skill accordingly.
Keep the single !!! note admonition at the top (the repo-pointer) so the "note" styling signals its role as a pointer, and downgrade the two mid-body callouts ("How accurate is this?" and "What changes when you switch currency...") to !!! info. Leaves the Top-income coverage warning untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a technical companion document for the global inequality visualization (the income-plots bespoke component in
owid-grapher) atdocs/analyses/inequality_visualization/index.md, registers it in the docs nav and on the analyses landing page, and adds a reusable Claude Code skill that captures the patterns used to produce it.The new doc
Sections covered:
etl/steps/data/external/owid_grapher/latest/int_dollar_conversions.py.The doc is now registered in
zensical.tomland has a card ondocs/analyses/index.md.The new skill (
create-analysis-doc)Prompts the user for the title, scripts, external data sources, and optional article URL, then drafts a doc to
ai/<short_name>.mdfollowing a canonical five-section skeleton (Introduction, Data sources, Methodology, Limitations, References) with guidance on when to add extra H2 sections. Covers style conventions (mkdocs-material admonitions, collapsible blocks, tables, worked examples), writing principles (lead with intuition, explain why, flag approximations), and the deployment flow (draft inai/→ copy todocs/analyses/→ register inzensical.toml→ add landing-page card → PR).Marked as
metadata.internal: trueper CLAUDE.md convention.Follow-ups (not in this PR)
[TODO: article URL]placeholder in the Introduction once the accompanying article URL is finalized.Test plan
make docs.servelocally, visithttp://localhost:9010/analyses/inequality_visualization/and confirm the page renders cleanly under Zensical/mkdocs-material./analyses/) shows the new card with a working Methodology button.create-analysis-docskill is picked up by Claude Code (appears in the skills registry) and that a test invocation prompts for inputs as designed.