Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New year, new docs! #148

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

New year, new docs! #148

wants to merge 1 commit into from

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!

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.

1 participant