Integration of equations in Docs. #5

Open
amitjamadagni opened this Issue Jun 10, 2015 · 2 comments

Comments

Projects
None yet
1 participant
@amitjamadagni
Member

amitjamadagni commented Jun 10, 2015

The current documentation does not include equations, this would require LaTeX in Docile. The issue hopes to get some references along these lines. Any pointers on these would also be helpful.

@amitjamadagni amitjamadagni changed the title from Integration of equations in Docile. to Integration of equations in Docs built using Docile. Jun 10, 2015

@amitjamadagni amitjamadagni changed the title from Integration of equations in Docs built using Docile. to Integration of equations in Docs. Jun 10, 2015

@amitjamadagni

This comment has been minimized.

Show comment
Hide comment
@amitjamadagni

amitjamadagni Jun 10, 2015

Member

An update : I had posted this in the Docile gitter room and here is the reply :

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.

Member

amitjamadagni commented Jun 10, 2015

An update : I had posted this in the Docile gitter room and here is the reply :

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.

@amitjamadagni amitjamadagni referenced this issue Jun 15, 2015

Merged

Attempt at integrating ode solvers. #8

2 of 2 tasks complete
@amitjamadagni

This comment has been minimized.

Show comment
Hide comment
@amitjamadagni

amitjamadagni Jun 16, 2015

Member

The QuODE types had duplication in the documentation. Again getting help from gitter room of Docile they have presented three options :

  • String the ops and then use in the loop
for op in [:a, :b, :c]
    text = "$(op)"
    @eval begin
        @doc $(text) ->
        $(op)(x) = x
    end
end
  • Have a common doc for QuODESolvers and then create a Dict for each of the subtypes
@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
  • Double interpolate the variable, same as first but not using text variable
for op in [:a, :b, :c]
    @eval begin
        @doc "$($(op))" ->
        $(op)(x) = x
    end
end
Member

amitjamadagni commented Jun 16, 2015

The QuODE types had duplication in the documentation. Again getting help from gitter room of Docile they have presented three options :

  • String the ops and then use in the loop
for op in [:a, :b, :c]
    text = "$(op)"
    @eval begin
        @doc $(text) ->
        $(op)(x) = x
    end
end
  • Have a common doc for QuODESolvers and then create a Dict for each of the subtypes
@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
  • Double interpolate the variable, same as first but not using text variable
for op in [:a, :b, :c]
    @eval begin
        @doc "$($(op))" ->
        $(op)(x) = x
    end
end
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment