Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    peter1000-extern
    @peter1000-extern

    Question regarding: !!include(filename):

    Just to confirm that I understand that correctly:

    "!!include(docs/longdocs.md)"
    a() = ()

    This will use as docstring the longdocs.md content but any !!meta within the longdocs.md is not extracted?

    If that is correct then maybe somthing to rethink: one could expect especial in long docstrings the need for some !!metas.

    Michael Hatherly
    @MichaelHatherly
    Yes, no metamacros are extracted from external docs currently. I was just erring on the side of caution. Adding that would be fine I think.
    peter1000-extern
    @peter1000-extern

    Just a quick thought I had looking through the current Docile documentation.

    Not wanting to disappoint you but I think the comments-asides without any source reference are
    more a vaste than any good.

    Cache

    Collector

    Formats

    I just read some and ask: What does that info help me like it is?

    Anyway, in my opinion with source line info it might be of some limited value or maybe to remove that category all together?

    I think do get rid of them for now with the Lexicon from master one would need to change here

    config = Config(md_subheader = :category, :category_order = [:module, :function, :method, :type, :typealias, :macro, :global] )
    Michael Hatherly
    @MichaelHatherly
    The Asides should probably be filtered out from that output. They'd be useful for doing some literate programming though, which was their main purpose.
    So they're not going anywhere ;)
    peter1000-extern
    @peter1000-extern
    What I meant above I think do get rid of them is to filter them for now - sorry probably not the best wording. I guess also with line numbers that they would have some values - anyway for Docile/Lexicon current docs it woulkd be better to filter them as suggested.
    Michael Hatherly
    @MichaelHatherly
    Oh, ok. That's clearer. Next time docs need a big rebuild I'll do that.
    Amit
    @amitjamadagni
    Hello everyone, just a small doubt on whether it is possible to integrate equations using LaTeX in docs ?
    Michael Hatherly
    @MichaelHatherly

    @amitjamadagni, the markdown parser should display LaTeX equations with a purple highlight in the REPL. Since $ and \ aren't treated as plain characters in docstrings you'll need to escape them with \ or you could define a string macro in your module to do it for you:

    macro L_str(text)
        text
    end

    and then apply it to docstrings like so:

    L"""
    Some maths:
    
    $$\int_a^b f(x) \, dx = 0$$
    """
    f(x) = x

    For static documentation generation the markdown output should preserve LaTeX syntax. The generated markdown files can then be passed to any program the handles LaTeX equations correctly, such as pandoc. I'm not sure how well mkdocs with ReadTheDocs will do currently.

    Michael Hatherly
    @MichaelHatherly
    Note that improvements to the static generation for things like LaTeX is planned for the upcoming 0.2 release.
    Amit
    @amitjamadagni
    Thank you very much for the reply :)
    Amit
    @amitjamadagni
    Hello everyone, we have been generating types using code generation at https://github.com/amitjamadagni/QuDynamics.jl/blob/ode/src/propodesolvers.jl
    I tried to generate custom docs for each type by passing \$op in the doc string but that does not seem to work ... any leads on this would be helpful ... Thanks
    Michael Hatherly
    @MichaelHatherly

    @amitjamadagni, the link 404'd but I guess you're referring to the latex branch in your fork? From looking at the docstring here you'll also need to escape the \ char for it to appear correctly in the resulting output generated by save.

    For actually rendering the markdown using mkdocs I'm having a bit of trouble with that today. Not sure why since it did work alright a few months back... it appears you need to install this extension to get it to work.

    Amit
    @amitjamadagni
    @MichaelHatherly sorry we have it now on master ... here is the link
    https://github.com/JuliaQuantum/QuDynamics.jl/blob/master/src/propodesolvers.jl
    no, I was not referring to the latex branch , sorry for the confusion ... the issue I had referred to previously, I am trying to make it work and that is on the latex branch ... but the problem we have currently is ... is there a way we could generate docs for generated code as in the above link
    in sense for instance we have generated different types by looping over the keys in the Dict type_to_method we would like to use the same keys for generating docs as well ... I tried passing in $op and \$op but these options dont seem to work ... any leads on this would be helpful
    Michael Hatherly
    @MichaelHatherly

    is there a way we could generate docs for generated code as in the above link

    The combination of @eval and string interpolation is probably raising a
    UndefVarError: op not defined error, yes? I've not had much success resolving
    that and it appears to still be a problem with Base.@doc as well.

    You can pull the interpolation outside of the @doc with something like:

    for op in [:a, :b, :c]
        text = "$(op)"
        @eval begin
            @doc $(text) ->
            $(op)(x) = x
        end
    end

    which should work with Docile.@doc and Base.@doc.

    Personally, what I've found is that documenting using loops tends to lead to repetitive
    docs where things might be better split up into a single doc for the general case and
    several other docs for the specific cases.

    In the context of QuODESolvers and their subtypes perhaps adding a general docstring
    to QuODESolvers and then anything more specific to each subtype op in the loop.

    @doc """
    ...
    """ ->
    abstract QuODESolvers <: QuPropagatorMethod
    
    const type_to_method = @compat Dict{Any, Any}(#...
    
    const subtypedocs = @compat Dict(#...
    
    for op in keys(type_to_method)
        text = subtypedocs[op]
        @eval  begin
            @doc $(text) ->
            immutable $op <: QuODESolvers
                options::Dict{Symbol, Any}
            end
            $op() = $op(Dict())
        end
    end

    where subtypedocs is a Dict containing the docstrings specific to each subtype.

    I've only skimmed over the package though, so that might go against how you'd like to
    organise things.

    Amit
    @amitjamadagni
    Thank you very much for the insight on this :)
    The combination of @eval and string interpolation is probably raising a
    UndefVarError: op not defined error, yes?
    Yes I had got that error ...
    Michael Hatherly
    @MichaelHatherly

    Thank you very much for the insight on this :smile:

    Sure, no prob.

    Yes I had got that error ...

    Yeah, best way around that is to just build up the docstring outside of the @eval block and then interpolate the value into it.

    You can "double interpolate" the value, but it is a bit more difficult to read I think:

    for op in [:a, :b, :c]
        @eval begin
            @doc "$($(op))" ->
            $(op)(x) = x
        end
    end
    Leo-C
    @Leo-C

    Hi, I've a problem in Lexicon, but I write in Docile room chat because I have some trouble in Docile under Lexicon.

    I create a new demo-module with command:

    Pkg.generate("TestMod","MIT")

    and then I've modified auto-generated TestMod.jl in:

    module TestMod
    
    "No-func"
    function testfunc()
    end
    
    end # module

    With following command all works well:

    using Lexicon
    using TestMod
    ?testfunc

    but command

    m = Docile.Interface.metadata(TestMod)

    return an empty ObjectIdDict.
    I think this is the cause for Lexicon to produce empty docuementation with save(). Have you some suggestion?

    Many thanks

    Leonardo

    Michael Hatherly
    @MichaelHatherly
    @Leo-C, I believe .metadata(TestMod) isn't picking up testfunc docs since the function definition is empty, try adding something to the function body, ie.
    "No-func"
    function testfunc()
        return 1
    end
    It's a known limitation since empty functions don't store a line number node which Docile needs to correctly identify them.