Updating a (still) private project to Julia 0.7/1.0

kellertuer · August 21, 2018, 12:29pm

I was a little slow on my package development and would like to upgrade these days from 0.6 to 0.7; I am still trying to get it properly working and have two problems that I looked for today for the last hour

I started with Pkg3 and did

develop ~/myPackage.jl/

that I worked on for some time and that uses (as kind of only dependency SimpleTraits.
Now when doing using myPackage in REPL I get

┌ Warning: Package Manopt does not have SimpleTraits in its dependencies:
│ - If you have myPackage checked out for development and have
│   added SimpleTraits as a dependency but haven't updated your primary
│   environment's manifest file, try `Pkg.resolve()`.
│ - Otherwise you may need to report an issue with Manopt
└ Loading SimpleTraits into Manopt from project dependency, future warnings for Manopt are suppressed.

But Pkg.resove does not change anything, and I could not figure out how to add that as a dependency (just add SimpleTraits in pkg>did not do the Job, that was the only thing I could find)…
Hot do I permanently and consistently add this dependency?

I have a lot of documentation using LaTeX since some of my documentation is easier to describe using formulae. Something like

    doc"""
    A documentation containing for example LateX like $\mathcal M$ to keep global information on a specific manifold
    """

worked fine in Julia 0.6 and I used it a lot.

Not in Julia 0.7 I get the deprecation warning

Deprecated syntax `doc" "` at /Users/bergmann/Repositories/Software/Manopt.jl/src/manifolds/Manifold.jl:17.
│ Use `@doc doc" "` instead.

But If I replace docwith @doc doc in the first line above (that’s how I understand that message) I get

WARNING: importing deprecated binding Base.@doc_str into MyPackage.
WARNING: Base.@doc_str is deprecated, use `Markdown` instead
  likely near /Users/bergmann/Repositories/Software/Manopt.jl/src/manifolds/Manifold.jl:14
ERROR: LoadError: LoadError: syntax: invalid interpolation syntax: "$ "

So it does not like my $ anymore and I haven’t found any documentation how to solve that. Why do I want to use $? Well that makes it easy to copy a few explaning formulae from my original markdown and latex files describing the theory in papers/talks. So: How can I keep the format of my docstrings?

tobias.knopp · August 21, 2018, 1:01pm

Do you have SimpleTraits in your REQUIRE file? If you do that and resolve afterwards, the issue will go away.

kellertuer · August 21, 2018, 1:10pm

Thanks, Haven’t found that in the documentation.

tobias.knopp · August 21, 2018, 1:18pm

yea, the current process is only documented in this forum. Once REQUIRE is obsolete the process will hopefully get more clear.

tobias.knopp · August 21, 2018, 1:41pm

you can quote the dollar sign \$ but I am not sure if this is what you want. The doc then does not render the latex code.

kellertuer · August 21, 2018, 1:43pm

Yes, but I’d also have to escape every latex commands \to \\and instead of that I could also use the Julia-style-mardkown `` `` to encapsulate LaTeX without escaping commands – that would all still mean to change the text. That’s what I liked about doc"""..."""

saschatimme · August 21, 2018, 1:50pm

kellertuer:

But If I replace doc with @doc doc in the first line above (that’s how I understand that message) I get
WARNING: importing deprecated binding Base.@doc_str into MyPackage.
WARNING: Base.@doc_str is deprecated, use `Markdown` instead
  likely near /Users/bergmann/Repositories/Software/Manopt.jl/src/manifolds/Manifold.jl:14
ERROR: LoadError: LoadError: syntax: invalid interpolation syntax: "$ "
So it does not like my $ anymore and I haven’t found any documentation how to solve that. Why do I want to use $? Well that makes it easy to copy a few explaning formulae from my original markdown and latex files describing the theory in papers/talks. So: How can I keep the format of my docstrings?

Did you try to add using Markdown to your imports?

tobias.knopp · August 21, 2018, 1:50pm

kellertuer · August 21, 2018, 1:52pm

Haven’t heard of it and did not understand the deprecation warning that way; Does that package directly interpreted strings as Markdown then?

saschatimme · August 21, 2018, 1:58pm

Markdown is one of the standard library packages and it seems that the function is now defined there

github.com

JuliaLang/julia/blob/4498d27c3c3e11effdfdfdce822d025079f01a0a/stdlib/Markdown/src/Markdown.jl#L45


      
          end
          
          
function docexpr(source::LineNumberNode, mod::Module, s, flavor = :julia)
              :($doc_str($(mdexpr(s, flavor)), $(QuoteNode(source)), $mod))
          end
          
          
macro md_str(s, t...)
              mdexpr(s, t...)
          end
          
          
function doc_str(md, source::LineNumberNode, mod::Module)
              md.meta[:path] = isa(source.file, Symbol) ? String(source.file) : ""
              md.meta[:module] = mod
              md
          end
          doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse(md), source, mod)
          
          
macro doc_str(s::AbstractString, t...)
              docexpr(__source__, __module__, s, t...)
          end

I don’t use this personally, but other packages seem to use this now this way:

github.com

Nemocas/AbstractAlgebra.jl/blob/09ae82a1546c43ed1870d79e807a05ae63177805/src/julia/Integer.jl#L43


      
          ###############################################################################
          
          
zero(::Integers{T}) where T <: Integer = T(0)
          
          
one(::Integers{T}) where T <: Integer = T(1)
          
          
if VERSION < v"0.7.0-DEV.1144"
          isone(a::Integer) = a == 1
          end
          
          
Markdown.doc"""
             isunit(a::Integer)
          > Return `true` if $a$ is $1$ or $-1$.
          """
          isunit(a::Integer) = a == 1 || a == -1
          
          
canonical_unit(a::T) where T <: Integer = a < 0 ? T(-1) : T(1)
          
          
###############################################################################
          #
          #   String I/O

kellertuer · August 21, 2018, 2:00pm

Thanks, that looks neat, couldn’t find that notation in the Markdown package. I will try to use it when I get my Atom back to accepting Julia. It just decided to automatically update to the Julia-Atom 0.17.0 that now crashes Julia on start -.-

kellertuer · August 21, 2018, 2:29pm

So, I tested the Markdown.doc idea – it does compile fine (already on Julia 1.0 since I resolved all deprecation warnings) – but while all non-Markdown strings nicely show up in ?FctName a FctWithMarkdownfunction just yields no documentation found.

kellertuer · August 21, 2018, 4:53pm

While somehow neither md""" nor Markdown.doc"""does seem to work on Julia 0.7, after I fixed all other Deprecation warnings now the tip of using @doc doc"""actually does work; I am just not sure why it did not in the first place.