Skip to content

New year, new docs!#148

Merged
tomreitz merged 10 commits intomainfrom
feature/docs_update
Mar 28, 2025
Merged

New year, new docs!#148
tomreitz merged 10 commits intomainfrom
feature/docs_update

Conversation

@tomreitz
Copy link
Collaborator

@tomreitz tomreitz commented Jan 8, 2025

This PR is an overhaul of the earthmover docs. Specific changes include:

  • Switch from a single README.md file to a docs site driven by Material & MkDocs (the same framework used for enabledataunion.org), which can be deployed to GitHub Pages via an automation, and which comes with a lot of nice features (like docs search). All the content from the old README.md has been moved into the docs site (with some slight edits and formatting changes). The docs site can be served locally with pip install mkdocs-material && mkdocs serve.

image

  • Switch to new EA branding/logo for earthmover (1).
  • Split the content from README.md (which was getting quite long) into several pages (2).
  • Organize headings on various pages to make in-page Table of Contents (left side) cleaner and facilitate docs section linking.
  • Add a gif demo and quick-start guide to "Home" page.
  • Add a "Learn" page to help new users become more familiar with the building blocks of earthmover, YAML and Jinja.

image

  • Change verbiage to better align to dbt: "earthmover project" and "packages" (instead of "bundles")
  • Add configuration examples for various different types of sources on the "Project configuration" page.

image

  • Add "Comparison to dbt" section to "Design" page.
  • Use Material features like Admonitions and Content tabs throughout.

image

My hope is that these improvements to the earthmover documentation will both be helpful to users and make it easier to continue to expand the docs as earthmover development continues.

If this PR is merged to main, I believe the docs should automatically appear at https://edanalytics.github.io/earthmover. README.md is now a thin description of earthmover pointing to that link, so when deployed, other places that show README.md (like PyPI) should also direct folks to the new docs site.

I would recommend that reviewers check out this branch, stand up these docs locally, and review them in detail. Feel free to leave comments about specific content changes, as well the general approach. Thanks!

@tomreitz tomreitz merged commit 351a6db into main Mar 28, 2025
@tomreitz tomreitz deleted the feature/docs_update branch March 28, 2025 21:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants