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

Closed
dcarrera opened this Issue Dec 20, 2013 · 8 comments

Comments

Projects
None yet
6 participants
Contributor

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

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.

Owner

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.

Member

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.

Owner

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.

Contributor

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.

Owner

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.

Owner

StefanKarpinski commented Dec 22, 2013

Ok, carry on and discuss.

Contributor

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

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

Open

Is there detailed manual for Rif.jl? #38

Owner

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