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

[Markdown] added doc string for @md_str string literal #52606

Merged
merged 19 commits into from
Jan 6, 2024

Conversation

mitiemann
Copy link
Contributor

This PR addresses #51168 . I guess this PR wants to have the labels doc & markdown .

@mitiemann mitiemann marked this pull request as ready for review December 22, 2023 13:02
@mitiemann
Copy link
Contributor Author

mitiemann commented Dec 22, 2023

Hello, world! This is my first PR to julia, some I'd be grateful for feedback. In particular:

  • Maybe it would be nice adding an example with a jldoctest. However, as md"# Hello, world!" is pretty-printed in the REPL, I'm wondering how to do this elegantly? Maybe wrapping it in an HTML renderer?
  • I've noticed @doc_str also doesn't have a docstring as of yet. However, I'm wondering whether this should really be part of the exposed API?

@mitiemann
Copy link
Contributor Author

There is a simultaneous PR for this issue at #52607 . We're currently figuring out which aspect of which PR to keep.

@mitiemann mitiemann force-pushed the mitie/md_str_doc branch 2 times, most recently from 54e0f67 to c06aebd Compare December 28, 2023 12:36
@mitiemann mitiemann force-pushed the mitie/md_str_doc branch 2 times, most recently from 4192b48 to 07a0ae7 Compare January 2, 2024 09:54
NEWS.md Outdated Show resolved Hide resolved
@mitiemann mitiemann force-pushed the mitie/md_str_doc branch 4 times, most recently from aef4d9b to c6924f6 Compare January 3, 2024 14:51
@mitiemann
Copy link
Contributor Author

Okay, I believe this would be ready to merge @stevengj . This is my first Julia PR. Is there anything else from my side that I could help to merge this?

@@ -40,6 +44,18 @@ function docexpr(source::LineNumberNode, mod::Module, s, flavor = :julia)
:($doc_str($(mdexpr(s, flavor)), $(QuoteNode(source)), $mod))
end

"""
macro md_str(s)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
macro md_str(s)
@md_str -> Markdown.MD

to match the convention used here https://docs.julialang.org/en/v1/base/strings/#Base.Docs.@html_str

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've copied the convention I found in Artifacts.@artifact_str. If I find the time, I'll try to find all (string literal) macro docs, check for their conventions and file an issue if I find too many divergent styles.

@fonsp fonsp added docs This change adds or pertains to documentation markdown labels Jan 4, 2024
@mitiemann
Copy link
Contributor Author

Thanks :-) Should I squash the commits myself or is this handled during merging? Also, only merge after #52733 has been merged as index.md now also includes Markdown.html and Markdown.latex.

@stevengj
Copy link
Member

stevengj commented Jan 4, 2024

Github will squash for you, so you needn't bother.

mitiemann and others added 2 commits January 5, 2024 01:04
Co-authored-by: Steven G. Johnson <stevenj@mit.edu>
@vtjnash vtjnash added the merge me PR is reviewed. Merge when all tests are passing label Jan 5, 2024
@vtjnash vtjnash changed the title added doc string for @md_str string literal [Markdown] added doc string for @md_str string literal Jan 5, 2024
@stevengj
Copy link
Member

stevengj commented Jan 5, 2024

CI failures seem unrelated.

@stevengj
Copy link
Member

stevengj commented Jan 6, 2024

CI failures are unrelated (#52506 etc.)

@stevengj stevengj merged commit 513d013 into JuliaLang:master Jan 6, 2024
5 of 7 checks passed
@IanButterworth IanButterworth removed the merge me PR is reviewed. Merge when all tests are passing label Jan 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation markdown
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants