Package Documentation

You first need a minimal init.el file to configure Emacs.

(package-initialize)

(require 'ess-site)
;; if required
;; (setq  inferior-julia-program-name "/path/to/julia-release-basic")

(require 'org)
;; *replace me* with your own ob-julia.el file location 
(add-to-list 'load-path "~/GitLab/WorkingWithOrgMode/EmacsFiles")
;; babel configuration
(setq org-confirm-babel-evaluate nil)
(org-babel-do-load-languages
 'org-babel-load-languages
 '((julia . t)))

Then you need a documented module:

module Foo

export Point, foo
    
import Base: norm

#+Point L:Point_struct
# This is my Point structure
#
# *Example:*
#
# Creates a point $p$ of coordinates $(x=1,y=2)$.
#
# #+BEGIN_SRC julia :eval never :exports code
# p=Point(1,2)
# #+END_SRC
#
# You can add any valid Org mode directive. If you want to use
# in-documentation link, use [[norm_link_example][]]
#
struct Point
    x::Float64
    y::Float64
end

#+Point
# Creates Point at origin $(0,0)$ 
Point() = Point(0,0)

#+Enum
# An enum
@enum Alpha A=1 B C # just for example

#+Point,Method L:norm_link_example
# A simple function that computes $\sqrt{x^2+y^2}$
#
# *Example:*
#!p=Point(1.0,2.0);
#!norm(p) 
#
# See: [[Point_struct][]]
#
norm(p::Point)::Float64 = sqrt(p.x*p.x+p.y*p.y)

# +Method,Internal
# An internal function
#
# For symbol that are not exported, do not forget the "Foo." prefix:
# !p=Point(1.0,2.0)
# !Foo.foo(2.0,p)
foo(r::Float64,p::Point) = Point(r*p.x,r*p.y)

end 

I wanted to reduce the documentation process as much as possible. The template is very simple. Before each item you want to document add these comment lines:

#+Tag1,Tag2,... L:an_extra_link_if_required 
#
# Here you can put any Org mode text, for instance $sin(x)$
#
#!sin(5) # julia code to be executed
#
# [[internal_link][]]
struct A_Documented_Struct 
...
end 

• #+Tag1,Tag2,… is mandatory, "#+" is followed by a list of tags. Later when you want to extract doc you can do filtering according these tags.
• L:an_extra_link_if_required is not mandatory. It defines a reference if you want to create doc links. The previous statement defines a link target named an_extra_link_if_required.
• [[internal_link][]] creates a link to a previously defined L:internal_link.
• !sin(5) will execute Julia code and include the output in the doc. If you only want to include Julia code without executing it, simply use Org mode source block:

# #+BEGIN_SRC julia :eval never :exports code
# sin(5)
# #+END_SRC

This is the foo.org file.

#+PROPERTY: header-args:julia :session *my_session* :exports code :eval no-export
#+OPTIONS: ^:{}
#+TITLE: Getting Started with a minimal example

#+BEGIN_SRC julia :results output none :eval no-export :exports none
push!(LOAD_PATH,pwd())
#+END_SRC

#+BEGIN_SRC julia :results output none :eval no-export :exports none
using J4Org 
initialize_boxing_module(usedModules=["Foo"]) 
documented_items=create_documented_item_array("Foo.jl")
#+END_SRC

* Example

Prints all documented items, except those tagged with "Internal" 
#+BEGIN_SRC julia :results output drawer :eval no-export :exports results
print_org_doc(documented_items,tag_to_ignore=["Internal"],header_level=0)
#+END_SRC

• push!(LOAD_PATH,pwd()) tells Julia where it can find our local Foo module. This statement is only required if the documented module is in an unusual place.
• using J4Org uses this package
• initialize_boxing_module(usedModules=["Foo"]) defines what are the modules to use when executing Julia code extracted from the doc (the "#!" statements). Here we are documenting the Foo module, hence we must use it. Note that you can also use any number of extra modules for instance with ["Foo", "ExtraModule", ...]. See initialize_boxing_module(…) for further details.
• create_documented_item_array("Foo.jl") creates the list of documented items from file "Foo.jl". You can use a list of files and a directory, see create_documented_item_array(…) for further details.
• print_org_doc(documented_items,tag_to_ignore=["Internal"],header_level=0) prints all documented items, except those tagged with "Internal", see print_org_doc(…) for further details

To check that it works you can start a fresh emacs with

emacs -q --load init.el foo.org &

then type:

• C-c C-v b + RET to execute all source code blocks
• C-c C-e h o to html-export the file
• C-c C-e l o to pdf-export the file

You should get this minimal_example/foo.html file.

This was a minimal example, you can have a better look for the exported documents by including css theme, etc. This is the approach we used to generate this document (also see the main.pdf PDF file). Another example is DirectConvolution.jl documentation.

This integer can have these values:

• -1: do not print header nor index, see header_level=-1
• 0: print header beginning with "-", see header_level=0.
• l>0 create subsection of level l, for instance header_level=3 creates subsections beginning with 3 stars. See header_level=5. Caveat: for l>0 AFAIK there is a bug in OrgMode, because a residual :RESULT: is printed.

These options allow to select items to include:

• tag a string or an array of strings, collects all items with at least one tag in this tag option.
• tag_to_ignore a string or an array of strings, ignore all items with at least one tag in this tag_to_ignore option.
• identifier a string that stands for the structure, abstract type or function name. Collects all items with this identifier name.

For instance we can print norm identifier, restricted to Point tag, as follows:

#+BEGIN_SRC julia :results output drawer :eval no-export :exports results
documented_items=create_documented_item_array("minimal_example/Foo.jl");
print_org_doc(documented_items,identifier="norm", tag="Point",header_level=-1)
#+END_SRC

This will generate:

norm(p::Point)::Float64

A simple function that computes \(\sqrt{x^2+y^2}\)

Example:

p=Point(1.0,2.0);
norm(p) 

2.23606797749979

See: struct Point

Foo.jl:35

If you look back at tag, tag_to_ignore, identifier you can see, at the end of the norm function documentation, that the Point_struct link is not active. The reason is that the Point structure is not present. The complete_link option, if set to true will try to fix all dangling links by including all the required documented items. For instance, with:

#+BEGIN_SRC julia :results output drawer :eval no-export :exports results
documented_items=create_documented_item_array("minimal_example/Foo.jl");
print_org_doc(documented_items,identifier="norm", tag="Point",header_level=-1,
              complete_link=true)
#+END_SRC

This will generate:

struct Point

This is my Point structure

Example:

Creates a point \(p\) of coordinates \((x=1,y=2)\).

p=Point(1,2)

You can add any valid Org mode directive. If you want to use in-documentation link, use norm(…)

Foo.jl:8

norm(p::Point)::Float64

A simple function that computes \(\sqrt{x^2+y^2}\)

Example:

p=Point(1.0,2.0);
norm(p) 

2.23606797749979

See: struct Point

Foo.jl:35

you see that the Point structure is included to make the struct_Point link active.

You can create link from your OrgMode document to Julia documented items that have defined a "L:link_target". However like these items can be extracted at several places in your OrgMode document you need to define a prefix to avoid multiple targets with the same name.

For instance, chose a prefix, here "my_prefix" and use:

print_org_doc(documented_items,...,link_prefix="my_prefix_")

then you can create a regular OrgMode link to this item using ​ [​[my_prefix_link_target][some_text]].

When set to true, generates an index as follows:

[A] ..., [B] ...,[a] ..., [b] ...,

When set to false, do not split upper/lower cases and group all A,a;B,b together:

[A] ..., [B] ...

Comments starting with "#!" are executed in a boxed environment

module MyBoxing
using RequiredPackage_1,RequiredPackage_2,...
end 

using MyBoxing

# execute "#!" statements here

This boxing is defined by the initialize_boxing_module(…) function:

initialize_boxing_module(boxingModule="MyBoxing",
                         usedModules=["RequiredPackage_1","RequiredPackage_2",...])

This boxingModule option allows you to chose your boxing environment:

print_org_doc(documented_items,boxingModule="MyBoxing",...)

Add: is_enum() and skip_enum_block() functions

Add: struct Extracted_Enum and extract_enum() function.

Then complete extract_code() to take into account the extracted Documented_Item.

This is not mandatory, however if you want to magnify link to enum, you can update the create_link_readable_part() function.

Add the is_documented_enum_type() function.