# LaTeX-syntax in docstrings with \`DocStringExtensions.jl\`

**URL:** <https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251>\
**Category:** Specific Domains\
**Tags:** documentation\
**Created:** [September 10, 2024, 1:49pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251 "2024-09-10T13:49:22Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![johannesnauta](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johannesnauta/32/47434_2.png) [@johannesnauta](https://discourse.julialang.org/u/johannesnauta)\
**Post date:** [September 10, 2024, 1:49pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/1 "2024-09-10T13:49:22Z")

</div>

I am working on a package that will be used by a small team, so I am trying to use `Documenter.jl` in conjunction with `DocStringExtensions.jl` to generate the documentation while writing an decorating functions – as one should.

However, I would like to include LaTeX in my docstrings, for example the equation for a specific system that is handled by a generic function. Yet, I’d highly prefer to not escape many characters (like `\\times`, etc.) when the equations grow in size.

One way is to include the `@doc raw """ ...` prefix, which makes these escape sequences not needed anymore, but these also make `DocStringExtensions` essentially useless as the `$(SIGNATURES)` or `$(TYPEDSIGNATURES)` now do not work as these are interepreted as `raw` strings.

For example take this docstring for some function:

````julia
@doc raw"""
    
    $(TYPEDSIGNATURES)

A function with some arguments, and an equation

```math
    f(x) = \int_0^\infty \frac{dx}{1+x^2}
```

# Arguments
- `x::Float64`: x
- `y::Float64`: y
"""
function f(x::Float64, y::Float64)
    nothing
end

````

When compiling the documentation, simply `$(TYPEDSIGNATURES)` is printed, instead of what is supposed to come out of it.

Is there any way to both include LaTeX syntax without excessive escaping, or is there a better way to “automatically” include function arguments in the docstring _without_ having to type them manually? If not, is there any good argument for typing them manually? Or how should one approach documentation of (relatively) large packages with many functions?

Any help or tips is greatly appreciated. Thank you! 🙂

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [September 10, 2024, 2:44pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/2 "2024-09-10T14:44:10Z")

</div>

> [@johannesnauta](#):
>
> Is there any way to both include LaTeX syntax without excessive escaping

You could use a [custom string macro](https://github.com/JuliaStrings/LaTeXStrings.jl/blob/fb11e8dc9c5a13091bb6d1ec1884a5aafbc34845/src/LaTeXStrings.jl#L68-L92) instead of `raw"..."`, similar to LaTeXStrings.jl which allows both unescaped `\` and variable interpolation with `%$`:

```julia
julia> using LaTeXStrings

julia> foo = 7
7

julia> L"""
       foo = %$foo

       an equation $\sqrt{\frac{1}{1+x^2}}$.
       """
L"foo = 7

an equation $\sqrt{\frac{1}{1+x^2}}$.
"

```

e.g.

```julia
macro myL_str(s::String)
    i = firstindex(s)
    buf = IOBuffer(maxsize=ncodeunits(s))
    ex = Expr(:call, :string)
    while i <= ncodeunits(s)
        c = @inbounds s[i]
        i = nextind(s, i)
        if c === '$' && i <= ncodeunits(s)
            position(buf) > 0 && push!(ex.args, String(take!(buf)))
            atom, i = Meta.parseatom(s, i, filename=string( __source__.file))
            Meta.isexpr(atom, :incomplete) && error(atom.args[1])
            atom !== nothing && push!(ex.args, atom)
            continue
        else
            print(buf, c)
        end
    end
    position(buf) > 0 && push!(ex.args, String(take!(buf)))
    return esc(ex)
end

```

which should do what you want (supports interpolation with `$` and supports unescaped backslashes), I think.

---

<div class="post-metadata">

**Author:** ![johannesnauta](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johannesnauta/32/47434_2.png) [@johannesnauta](https://discourse.julialang.org/u/johannesnauta)\
**Post date:** [September 10, 2024, 2:53pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/3 "2024-09-10T14:53:17Z")

</div>

This raises an error when building the documentation.

```julia
L"""
These are some docs
"""
function doctest(x::Int)
	  nothing
end

```

then in `/docs/src/index.md`

````md
```@docs
MyPkg.doctest
```

````

and running `julia --project make.jl` in `/docs/` gives

```julia
ERROR: LoadError: `makedocs` encountered an error [:docs_block] -- terminating build before rendering.

```

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [September 10, 2024, 2:55pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/4 "2024-09-10T14:55:15Z")

</div>

> [@johannesnauta](#):
>
> This raises an error when building the documentation.

You still need `@doc` if you want to use a string macro (or anything other than an ordinary literal string) for documentation, I think.

And I would use `@doc myL"..." foo` rather than `L"..."` from LaTeXStrings, because you want the documentation string to be a `String` and not a `LaTeXString`. That’s why I said to use a macro _similar to_ the one in LaTeXStrings.

---

<div class="post-metadata">

**Author:** ![johannesnauta](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johannesnauta/32/47434_2.png) [@johannesnauta](https://discourse.julialang.org/u/johannesnauta)\
**Post date:** [September 10, 2024, 3:04pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/5 "2024-09-10T15:04:53Z")

</div>

Yeah sorry I was a bit too fast with my first reply. Still, using your macro and some equation in the string gives errors that things within the equation are not defined, e.g.,

```julia
@doc CustomL"""
These are some docs, with an inline equation $f(x) = 2x$.
"""
function doctest(x::Int)
	  nothing
end

```

gives rise to the error that

```julia
ERROR: LoadError: UndefVarError: `f` not defined

```

I am not super familiar with macros and this kind of string-manipulation, so I am not fully sure what your macro is trying to achieve. I also cannot believe I am the only one with this problem? Or do people generally not use `DocStringExtensions.jl` and just type function signatures manually?

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [September 10, 2024, 3:31pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/6 "2024-09-10T15:31:55Z")

</div>

> [@johannesnauta](#):
>
> Still, using your macro and some equation in the string gives errors that things within the equation are not defined, e.g.,

Yes, if you want to use the deprecated `$` as an equation delimiter (rather than ````, which is [encouraged](https://documenter.juliadocs.org/stable/man/latex/)), then you will need to use something else for interpolation. e.g. LaTeXStrings uses `%$` for interpolation, and you can copy the code for that if you want (just change the first line of the `L_str` macro to call `string` instead of `latexstring`).

---

<div class="post-metadata">

**Author:** ![johannesnauta](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johannesnauta/32/47434_2.png) [@johannesnauta](https://discourse.julialang.org/u/johannesnauta)\
**Post date:** [September 10, 2024, 3:49pm UTC](https://discourse.julialang.org/t/latex-syntax-in-docstrings-with-docstringextensions-jl/119251/7 "2024-09-10T15:49:58Z")

</div>

Ah that is great, was not aware that I could use `` instead of `$` to indicate math, which is indeed much clearer. Thanks a lot. I will try to understand the macro a bit better and add it to my codebase.