Julia Domain¶

This extension provides a sphinx domain for the Julia language using the name jl. A domain is basically a collection of directives and roles which define markup constructs that then can be rendered to different outputs like html and latex. E.g. the python domain provides the directives py:class, py:exception, py:method, py:classmethod, py:staticmethod, py:attribute, py:module, py:currentmodule, py:decorator and py:decoratormethod. Additionally it provides tools for indexing and cross-referencing these constructs.

Reusing the python implementation is mostly not possible since the underlying model of Python and Julia are too different. E.g. Julia has no notion of methods associated to classes and therefore py:method, py:classmethod, py:staticmethod are all meaningless concepts. On the other hand Julia implements abstract types, type restraints and macros.

Directives¶

Types¶

There are two directives type and abstract representing composite types and abstract types respectively. Both of them are rather straight forward to use. E.g.

.. jl:abstract:: Theory

    The general principles or ideas that relate to a particular subject

.. jl:type:: QuantumTheory <: Theory

     A theory based on the idea that energy is made of small separate units of energy.

is rendered as

abstract Theory¶
The general principles or ideas that relate to a particular subject.
type QuantumTheory<: Theory¶
A theory based on the idea that energy is made of small separate units of energy.

Modules¶

Modules are created by using the module directive and can be used to group other objects together. They can also be nested and provide a common namespace which is indicated by indentation and can be seen in the following example

.. jl:module:: linalg

    .. jl:abstract:: Array

        General array type.

    .. jl:module:: sparse

        Sparse linear algebra functionality.

        .. jl:type:: SparseMatrix <: Array

            Sparse matrix implementation.

    .. jl:type:: Matrix <: Array

        Dense matrix implementation.

which gives the following output

module linalg¶
abstract Array¶
General array type.
module sparse¶
Sparse linear algebra functionality.

type SparseMatrix<: Array¶
Sparse matrix implementation.
type Matrix<: Array¶
Dense matrix implementation.

Functions¶

Using the directive jl:function allows us to define a function by giving the functions signature as argument. The simple example

.. jl:function:: f(a)

renders as

function f(a)¶

Additional text in the body of the directive can be used for documentation of the function

.. jl:function:: f(a::Int, b=1)

    Detailed explanation of everything.

and looks like

function f(a, b)¶
Detailed explanation of everything.

Also more complicated signatures are possible and also most of the roles defined for the python domain can be used allowing for a nice description of the parameters. E.g.

.. jl:function:: myfunc{T}(a::T, b=1; state="Foo", flag::Boolean, kwargs...)

    Solve all the things.

    :param a: Very important parameter
    :type a: T
    :param b: Not so important parameter
    :kwparam state: It's a trap.
    :kwparam flag: Do. Or do not. There is no try.

gives the following output

function myfunc{T}(a; b, flag)¶
Solve all the things.

Parameters:

a (T) – Very important parameter

b – Not so important parameter

Keyword Parameters:

state – It’s a trap.

flag – Do. Or do not. There is no try.

Roles¶

Every directive introduced above can be referenced via the roles type, abstract, mod and func.

Using :jl:type:`Matrix` (Matrix) and :jl:abstract:`Array` (Array) creates references to these types .

Targets can be referenced fully qualified :jl:mod:`linalg.sparse` (linalg.sparse) or shortened as :jl:mod:`sparse` (sparse).

Functions are in the simplest case identified just by their name, e.g. :jl:func:`myfunc` (myfunc). In order to distinguish between methods of the same name one can additionally use pattern matching like :jl:func:`f(a)` (f(a)), :jl:func:`f(a,b)` (f(a,b)), :jl:func:`f(a::Int,)` (f(a::Int,)) or :jl:func:`f(,=1)` (f(,=1)).