[CT-3427] [CT-3415] [Feature] LaTeX rendering in DBT docs
Closed this issue · 3 comments
Is this your first time submitting a feature request?
- I have read the expectations for open source contributors
- I have searched the existing issues, and I could not find an existing issue for this feature
- I am requesting a straightforward extension of existing dbt functionality, rather than a Big Idea better suited to a discussion
Describe the feature
When writing doc blocks, sometimes it's useful to include formulas of the calculation so other users know precisely how a particular metric is defined. Currently, DBT supports Markdown rendering in its docs. LaTeX is the typical way to write formulae, and is supported by a large range of Markdown "flavours". It should be fairly simple to add a LaTeX preprocessor to the DocumentationParser.parse_block() method, which could be bundled as an optional dependency to ensure no performance hit for existing users.
Describe alternatives you've considered
- Writing code blocks into the doc string helps sometimes, but choice of language and implementation details sometimes make the intent unclear.
- "Verbal" descriptions work for simple formulae, but sometimes things like algebraic substitutions get messy if using words to describe formula substitutions
- External documentation breaks one of the nice things about DBT, that it all lives in one codebase!
Who will this benefit?
- Maintainers of the DBT model who are governing more complex metrics
- Anyone who needs a little more flexibility in writing their docs
- Teams that work closely with data scientists or other Jupyter-like markdown standards
It also keeps DBT in line with how Markdown works on a lot of platforms (e.g. Github)
Are you interested in contributing this feature?
I'd be happy to implement, given some road rules esp. about bundling additional packages
Anything else?
Not a huge priority, obviously, but would be a nice QoL boost for better docs.
Interesting to note, Latex support for math is being integrated into mermaid.js: mermaid-js/mermaid#2885, and there's already a PR open to add mermaid.js to dbt: #375
This issue has been marked as Stale because it has been open for 180 days with no activity. If you would like the issue to remain open, please comment on the issue or else it will be closed in 7 days.
Although we are closing this issue as stale, it's not gone forever. Issues can be reopened if there is renewed community interest. Just add a comment to notify the maintainers.