Overhaul custom entities page

[kmoscoe]

This PR completely rewrites the custom entities page to cover only the explicit method of defining them. It also adds an expanded section on enums and restructures everything.

Staged at http://bullie.svl.corp.google.com:4000

[gemini-code-assist]

Summary of Changes

Hello @kmoscoe, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly overhauls the documentation for defining custom entities, now referred to as non-place entities. The primary focus has shifted to the explicit method of entity definition using MCF and CSV files, removing previous implicit schema discussions. The changes also include an expanded section on how to define and use enumerations for entity types, and a clearer explanation of how statistical variables are defined and linked to these entities. The overall structure of the related documentation has been reorganized to improve clarity and user guidance.

Highlights

• Documentation Restructuring: The primary documentation page for custom entities (custom_entities.md) has been completely rewritten and reorganized for improved clarity and flow.
• Explicit Entity Definition Focus: The documentation now exclusively covers the explicit method of defining custom entities using MCF and CSV files, removing previous discussions of implicit schema for a more streamlined approach.
• Enhanced Enumeration Guidance: An expanded section on enumerations (enums) has been added, detailing their definition in MCF and illustrating their usage for subclassing entity types, providing clearer guidance for complex data models.
• Clarified Statistical Variable Handling: The process for defining and extending statistical variables, including the use of populationType and MCF, has been clarified and integrated into the custom_data.md file for better context.
• Updated Terminology: The term "custom entities" has been consistently updated to "non-place entities" across the documentation for better precision and consistency within the Data Commons ecosystem.

Changelog

• custom_dc/custom_data.md
  • Updated internal link text from "custom entities" to "non-place entities".
  • Expanded the "Entities and entity types" section to differentiate between populationType and aggregation level for non-place entities.
  • Modified text to indicate statistical variables can be "reuse or extend existing ones".
  • Added a sentence explaining that existing statistical variables can be extended by redefining them in an MCF file.
  • Inserted an anchor {: #json} before the "Step 3: Write the JSON config file" heading.
• custom_dc/custom_entities.md
  • Adjusted introductory text to clarify defining/extending custom non-place entities.
  • Rewrote the "Overview" section to remove implicit/explicit schema distinction and state that entity types are defined in MCF, while entities can be in MCF or CSV.
  • Changed "Step 1: Define custom entity types (if needed) using explicit schema" to "Prepare your data" and then "Step 1: Define new entity types (if needed)".
  • Detailed the required fields for MCF entity type definitions (Node, name, typeOf, subClassOf).
  • Introduced "Step 1a: Define enumerations for the entity type (optional)" with a new section and example for MCF enum definitions.
  • Renamed "Step 2: Define custom entities using implicit schema" to "Step 2: Define new entities" and updated its content to focus on CSV examples for entities, clarifying DCID usage, namespaces, and linking to existing entities.
  • Removed the previous section "Add statistical variables and observations for new entities".
  • Renamed "Step 3: Write the config.json file" to "Step 3: Write the config.json file" and updated the example JSON and its explanation to reflect the new structure (removing the entities block and simplifying input_files details).
  • Added a new "Step 4: Add statistical variables and observations for new entities" section, providing a detailed CSV example for observations and explaining populationType.
  • Added a new "Step 5: Add the observations CSV to config.json" section with an updated combined config.json example.
  • Added a detailed "Example enum definitions" section with MCF examples and explanations.
  • Updated the description for viewing non-place entities in the browser.
  • Removed a TODO comment about extending existing entities.
• custom_dc/quickstart.md
  • Removed an unnecessary blank line within a shell command block.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request provides a significant overhaul of the custom entities documentation, making it clearer and more focused on the explicit definition method. The restructuring and addition of an expanded enums section are excellent improvements. I've identified a few minor areas for improvement in the examples and text to enhance clarity and correctness.

[keyurva]

Thanks Kara!

[keyurva]

Should we briefly talk about or link entities and place entities in general before they dive into custom entities here?

[keyurva]

Looks like you have links later on but think about whether it makes sense to talk about it first up.

[kmoscoe]

It's explained at length in the linked sections, so I'd prefer not to repeat it here.

[keyurva]

Should have a blurb about why this is rare. One challenge today is that it is difficult to find what the existing types are.

[kmoscoe]

Again, this is discussed in the other page. I will link to it.