## Where communities thrive

• Join over 1.5M+ people
• Join over 100K+ communities
• Free without limits
##### 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
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
@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.