Manual/Tutorial/POD-style documentation in Julia programs #5200

dcarrera opened this Issue Dec 20, 2013 · 8 comments


None yet
6 participants

dcarrera commented Dec 20, 2013

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


This is Markdown documentation embedded in the code.
It includes [links](, images,
sample code,

        using ThisModule


and also supports pipe tables (supported by several

| 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.

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 commented Dec 20, 2013

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


pao commented Dec 20, 2013

@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 commented Dec 20, 2013

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 commented Dec 21, 2013

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 commented Dec 22, 2013

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


StefanKarpinski commented Dec 22, 2013

Ok, carry on and discuss.


dcarrera commented Dec 31, 2013

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

# AsciiDoc Example
= Product Manual

== Introduction
Blah blah blah

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

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.

@lgautier lgautier referenced this issue in lgautier/Rif.jl Oct 26, 2014


Is there detailed manual for Rif.jl? #38


ViralBShah commented Nov 22, 2014

For reference: #8514

@ViralBShah ViralBShah added the doc label Nov 22, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment