[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Using @defblock / @linemacro for API documentation

From: Luis Felipe
Subject: Re: Using @defblock / @linemacro for API documentation
Date: Sun, 19 Mar 2023 13:48:02 +0000
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.7.2


El 19/03/23 a las 11:40, Gavin Smith escribió:
(switching from help-texinfo to bug-texinfo)

On Mon, Mar 06, 2023 at 10:45:05PM +0900, Jean-Christophe Helary wrote:
I found the example with a nested @def* block interesting:

It reminded me of this thread:

Nested @def* could be a good way to define parameters, return values, and
so on. With the new @defline facility the user could define macros like
@param that expanded to "@defline Parameter".
That would be nice because I think those kinds of nested definitions make it easier 
to find the information you're looking for compared to defining parameters within the 
paragraphs that explain a given command, procedure, etc.<publickey - - 0x12DE1598.asc>

Here's an example of how @defline and @linemacro can be used together
to imitate the format of the numpy documentation at
(numpy was referred to in the previous discussion).

Currently this only works with texinfo.tex.

@linemacro param {param, type}
@defline Parameter @var{\param\} @code{ : \type\}
@end linemacro
@linemacro returns {param, type}
@defline {Return Value} @var{\param\} @code{ : \type\}
@end linemacro
@linemacro raises {exception}
@defline {Exception} \exception\
@end linemacro

@set txidefnamenospace
@clear txicodevaristt

@defline Function fft.fft (a, n=@code{None}, axis=@code{-1}, norm=@code{None})
Compute the one-dimensional discrete Fourier Transform.

@param a array_like
Input array, can be complex.

@param n int, optional
Length of the transformed axis of the output.
If @var{n} is smaller than the length of the input, the input is cropped.

@param axis int, optional
Axis over which to compute the FFT.

@returns out complex ndarray
The truncated or zero-padded input.

@raises IndexError
If @var{axis} is not a valid axis of @var{a}.

@end defblock

@end defblock

It looks great to me! Looking forward to using it in my documentation.

Attachment: OpenPGP_0x0AB0D067012F08C3.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]