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
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions stdlib/Markdown/docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -398,3 +398,17 @@ complex features (such as references) without cluttering the basic syntax.

In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely
custom flavour of Markdown can be used, but this should generally be unnecessary.

## [Markdown String Literals](@id stdlib-markdown-literals)

Markdown strings can be constructed using the string literal syntax `md"..."`.

## [API reference](@id stdlib-markdown-api)

```@docs
Markdown.MD
Markdown.@md_str
Markdown.@doc_str
Markdown.html
Markdown.latex
```
39 changes: 39 additions & 0 deletions stdlib/Markdown/src/Markdown.jl
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license

"""
Markdown

Tools for working with the Markdown file format. Mainly for documentation.
mitiemann marked this conversation as resolved.
Show resolved Hide resolved
The `Markdown` module provides the (internal) [`MD`](@ref) type as well as the string
literals `md"..."` and `doc"..."`.
"""
module Markdown

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

"""
@md_str -> MD

Parse the given string as Markdown text and return a corresponding [`MD`](@ref) object.

# Examples
```jldoctest
julia> s = md"# Hello, world!"
Hello, world!
≡≡≡≡≡≡≡≡≡≡≡≡≡

julia> typeof(s)
Markdown.MD

```
"""
macro md_str(s, t...)
mdexpr(s, t...)
end
Expand All @@ -51,6 +71,25 @@ function doc_str(md, source::LineNumberNode, mod::Module)
end
doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse(md), source, mod)

"""
@doc_str -> MD

Parse the given string as Markdown text, add line and module information and return a
corresponding [`MD`](@ref) object.

`@doc_str` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
the manual section on [documentation](@ref man-documentation) for more information.

# Examples
```
julia> s = doc"f(x) = 2*x"
f(x) = 2*x

julia> typeof(s)
Markdown.MD

```
"""
macro doc_str(s::AbstractString, t...)
docexpr(__source__, __module__, s, t...)
end
Expand Down
6 changes: 6 additions & 0 deletions stdlib/Markdown/src/parse/parse.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license

"""
MD

`MD` represents a Markdown document. However, `MD` objects should only be constructed using
stevengj marked this conversation as resolved.
Show resolved Hide resolved
the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
"""
mutable struct MD
mitiemann marked this conversation as resolved.
Show resolved Hide resolved
content::Vector{Any}
meta::Dict{Symbol, Any}
Expand Down