Ada Domain

Originally written by Tero Koskinen <[email protected]>, forked and modified by Raphaël Amiard <[email protected]> for AdaCore.

About

This extension adds Ada domain support to Sphinx. While you can write files documenting Ada code manually with this domain, it is mostly meant to be used together with the laldoc documentation generator, which is part of Libadalang.

This extension requires Python 3.7 minimum.

Architecture

The aim of the ada domain is to make it easy for an automatic tool to generate sphinx that documents Ada constructs, easy for a manual doc writer to reference generated doc, and not horribly hard for a manual API ref writer to write this by hand if he so chooses (even though we don't see why that would happen).

For this reason, profiles for Ada entities are written in almost Ada. The domain can use Libadalang to parse function profiles if it is available, but will fall-back on a simplistic regex in the case it's not.

Cross references

Unlike the old version of the Ada domain developed by Tero Koskinen, cross references are stored in one unique namespace (which is equivalent to the language semantics).

Fully qualified names should work already (so that if you write :ada:type:`Root_Pkg.Child.My_Type` in a docstring or a ReST file it should generate the proper cross referenced). Relative names are planned but not implemented.

Attention!

Cross references for overloaded subprograms are not handled yet. Only the first subprogram with a given FQN will be registered and referenceable. We have not yet chosen the scheme we want to use for this. The old scheme based on arity was very complex and not correct - since arity is not sufficient.

Available directives

This is a (non exhaustive for the moment) list of directives that this extension exposes.

function/procedure directives

Those directives are used to document subprograms. They're of the form:

.. ada:function:: function Foo (A, B : Integer) return Integer

    Documentation for the ``Foo`` function.

.. ada:procedure:: procedure Foo (A, B : Integer)

    Documentation for the ``Foo`` procedure.

field types:	parameter, returnvalue

object directive

This directive is used to document object declarations. It's of the form:

.. ada:object:: No_Such_Element : constant Element

    Documentation for the constant

    :defval: `(null record)`
    :objtype: Element

It doesn't include the default value in the profile, but as a field.

field types:	objtype, renames, defval

exception directive

This directive is used to document exceptions. It's of the form:

.. ada:exception:: Custom_Exception

    Documentation for the exception

generic-package-instantiation directive

This directive is used to document generic package instantiations. It's of the form:

.. ada:generic-package-instantiation:: package Charset is new Parse_Option

    Documentation for the generic package instantiation.

    :instpkg: GNATCOLL.Opt_Parse.Parse_Option

generic_package directive

This directive is used to document generic packages. It's of the form:

.. ada:generic_package:: Package_Name

    Documentation for the package

    .. ada:function: ....

package directive

This directive is used to document child packages. It's of the form:

.. ada:package:: Package_Name

    Documentation for the package

    .. ada:function: ....

set_package directive

This directive is used to set the current library level package. It's a top-level directive rather than a nesting one. you use it like this:

.. ada:set_package:: Current_Package

Doc for the package with corresponding directives

.. ada:function: ....

type directive

This directive is used to document types. You use it like this:

.. ada:type:: type My_Type

    Documentation for My_Type.

    :discriminant Boolean Kind:
    :component Integer My_Int_1:
    :component Integer My_Int_2:

field types:	discriminant, component