[BUG] Sublists Not Working in Docstrings

[TheCedarPrince]

Hi all! Thanks for making such a wonderful tool and making Julia even better and better!

I found an interesting bug when working on creating a docstring and trying to add in a sublist. Here is the docstring I was trying to make:

"""
    latex(text::LaTeXString, pos::Point, object::Symbol; valign::Symbol = :top, halign::Symbol = :left)

Add the latex string `text` to the top left corner of the LaTeX path.
Can be added to `Luxor.jl` graphics via [`Video`](@ref).

**NOTES:**
- **This only works if `tex2svg` is installed.**
    It can be installed using the following command (you may have to prefix this command with `sudo` depending on your installation):

        npm install -g mathjax-node-cli

- **The `latex` method must be called from within an [`Object`](@ref).**

# Arguments
- `text::LaTeXString`: a LaTeX string to render.
- `pos::Point`: position of the upper left corner of the latex text. Default: `O`
    - can be written as `x, y` instead of `Point(x, y)`
- `object::Symbol`: graphics objects defined by `Luxor.jl`. Default `:stroke`.
	- `:stroke` - Draws the latex string on the canvas. For more info check `Luxor.strokepath`
	- `:path` - Creates the path of the latex string but does not render it to the canvas.

Which I expected to be nicely formatted like this:

---

latex(text::LaTeXString, pos::Point, object::Symbol; valign::Symbol = :top, halign::Symbol = :left)

Add the latex string text to the top left corner of the LaTeX path.
Can be added to Luxor.jl graphics via Video.

NOTES:

• This only works if tex2svg is installed.
  It can be installed using the following command (you may have to prefix this command with sudo depending on your installation):

    npm install -g mathjax-node-cli
  

• The latex method must be called from within an Object.

Arguments

• text::LaTeXString: a LaTeX string to render.
• pos::Point: position of the upper left corner of the latex text. Default: O
  • can be written as x, y instead of Point(x, y)
• object::Symbol: graphics objects defined by Luxor.jl. Default :stroke.
  • :stroke - Draws the latex string on the canvas. For more info check Luxor.strokepath
  • :path - Creates the path of the latex string but does not render it to the canvas.

---

However, it ends up looking like this:

As one can see, the bullet for pos now contains the sub-bullet and the stroke and path sub-bullets were not rendered. Could anyone explain or help me figure out why this Markdown syntax does not work in docstrings?

Here is my versioninfo:

Julia Version 1.6.0-rc3
Commit 23267f0d46 (2021-03-16 17:04 UTC)
Platform Info:
  OS: Linux (x86_64-pc-linux-gnu)
  CPU: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-11.0.1 (ORCJIT, skylake)
Environment:
  JULIA_EDITOR = nvim

[TheCedarPrince]

This was also found by @xijiang and discussed over here: https://discourse.julialang.org/t/how-to-put-sublists-into-docstrings/57843

[fredrikekre]

Tabs -> Spaces?

[mbauman]

I also recently saw this on CSV.File's docstring, too:

    •  Column Type Options: • type: a single type to use for parsing an entire file; i.e. all columns will be treated as the same type; useful for matrix-like
       data files • types: a Vector or Dict of types to be used for column types; a Dict can map column index Int, or name Symbol or String to type for a column,
       i.e. Dict(1=>Float64) will set the first column as a Float64, Dict(:column1=>Float64) will set the column named column1 to Float64 and,
       Dict("column1"=>Float64) will set the column1 to Float64; if a Vector if provided, it must match the # of columns provided or detected in header •    •  Column Type Options: • type: a single type to use for parsing an entire file; i.e. all columns will be treated as the same type; useful for matrix-like
       data files • types: a Vector or Dict of types to be used for column types; a Dict can map column index Int, or name Symbol or String to type for a column,
       i.e. Dict(1=>Float64) will set the first column as a Float64, Dict(:column1=>Float64) will set the column named column1 to Float64 and,
       Dict("column1"=>Float64) will set the column1 to Float64; if a Vector if provided, it must match the # of columns provided or detected in header •

https://github.com/JuliaData/CSV.jl/blob/c386238f756d9465288c72b882bb68fcdf62ea3a/src/file.jl#L166-L174

[TheCedarPrince]

@fredrikekre - although this doesn't show it, I tested tabs and spaces and both have the same effect. I wonder if the Markdown parser somehow is not understanding the spacing/indenting...

[fredrikekre]

I also recently saw this on CSV.File's docstring, too:

That is #37232

@fredrikekre - although this doesn't show it, I tested tabs and spaces and both have the same effect. I wonder if the Markdown parser somehow is not understanding the spacing/indenting...

I can not reproduce it with just spaces, so I believe the problem is that you mix spaces and tabs in your example.

[mbauman]

Ah, I see. So using spaces give us #37232:

julia> @md_str """
       - `object::Symbol`: graphics objects defined by `Luxor.jl`. Default `:stroke`.
         - `:stroke` - Draws the latex string on the canvas. For more info check `Luxor.strokepath`
         - `:path` - Creates the path of the latex string but does not render it to the canvas.
       """
    •  object::Symbol: graphics objects defined by Luxor.jl. Default :stroke. - :stroke - Draws the latex string on the canvas. For more info check
       Luxor.strokepath - :path - Creates the path of the latex string but does not render it to the canvas.

Using tabs is also broken, but differently:

julia> @md_str """
       - `object::Symbol`: graphics objects defined by `Luxor.jl`. Default `:stroke`.
       \t- `:stroke` - Draws the latex string on the canvas. For more info check `Luxor.strokepath`
       \t- `:path` - Creates the path of the latex string but does not render it to the canvas.
       """
    •  object::Symbol: graphics objects defined by Luxor.jl. Default :stroke.

  - `:stroke` - Draws the latex string on the canvas. For more info check `Luxor.strokepath`
  - `:path` - Creates the path of the latex string but does not render it to the canvas.

[TheCedarPrince]

Hunh... Thanks for the sleuthing @mbauman - so there is two bugs here then. The one already reported by @KristofferC (#37232) and this new one with tabs. Do you know how I might go about fixing this?

[StefanKarpinski]

Bump?

[TheCedarPrince]

@StefanKarpinski - I never got any pointers or go ahead on this, but would be happy to help! Would be fun to make a small contribution to core Julia! 😄