Manual/Tutorial/POD-style documentation in Julia programs

[dcarrera]

I would very much like it if Julia had a native support for some sort of embedded documentation inside the source code which can be used to produce (say) a manual in HTML or PDF, or a man page. I am thinking of a feature similar to Perl's POD.

Issues that may be related to this one: #3988 #4579 #5135.

In light of the discussion in #3988, I am thinking along the lines of something like this:

@doc md"""
Product Manual
==============

Introduction
------------

This is Markdown documentation embedded in the code.
It includes [links](http://julialang.org), images,
sample code,

        using ThisModule

        example("foo")

and also supports pipe tables (supported by several
implementations):

| Header | Center | Right |
|--------|:------:|------:|
|  Cell  |  Cell  |  $10  |
|  Cell  |  Cell  |  $20  |
"""

function example(s="bar")
    @doc md"""
    Explanation of the `example` function. This can be
    inclued, for example, in the reference section or
    appendix of the manual.
    """
    ...
end

The md""" ... """ is a string macro for Markdown code. I would like to see Julia documentation give a choice of documentation languages like tex, rst, md, html and xml (e.g. docbook) and user-defined alternatives.

Then, an external program could extract the manual documentation from the source code. Perhaps something like this:

prompt $ juliadoc example.jl   # Generates example.tex
prompt $ pdflatex example.tex  # Generates example.pdf

Or maybe:

prompt $ juliadoc --topdf example.jl
prompt $ juliadoc --tohtml example.jl
prompt $ juliadoc --toijulia example.jl

This discussion seems relevant to issue #4579 because you can think of IJulia notebooks as a possible output format for Julia documentation, to complement HTML and PDF output.

[StefanKarpinski]

I'm not sure why you opened a dup of #3988 and then linked to it from that same issue.

[pao]

@dcarrera's comment in #3988 indicates that he felt this was in fact off-topic, which probably means the topic of that issue is no longer clear.

[StefanKarpinski]

Yeah, ok, fair enough. I just find that I'd rather search through a long issue than try to remember a half dozen issue that the discussion is spread across. But yeah, it's probably fine to have this too.

[dcarrera]

I would be happy to have this issue closed. I thought that @stevengj said that issue #3988 is only about documenting objects. I took that to mean that I was moving off topic. I am happy to close this issue if that's better.

[stevengj]

@StefanKarpinski, I don't think it is a dup if we are talking about documentation not specifically associated with Julia objects.

[StefanKarpinski]

Ok, carry on and discuss.

[dcarrera]

Another alternative is to use @doc only for reference documentation and interpret unassigned strings as documentation. For example:

# AsciiDoc Example
adoc"""
= Product Manual

== Introduction
Blah blah blah
"""

@doc adoc"""
This is how function foo() works...
"""
function foo()
   ...
end

My thinking is that, in order to generate a manual we probably want an external program anyway (e.g. juliadoc myprogram.jl), so I'm not sure what one would gain from the @doc macro.

[ViralBShah]

For reference: #8514