Re: Using @defblock / @linemacro for API documentation

Luis Felipe <[email protected]> Sun, 19 Mar 2023 13:48:02 +0000

Newsgroups	gmane.comp.tex.texinfo.general
Message-ID	<[email protected]>

Hi,

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:
>>>>
>>>> https://luis-felipe.gitlab.io/texinfo-css/Elements.html#Definitions
>>>>
>>>> It reminded me of this thread:
>>>>
>>>> https://lists.gnu.org/archive/html/bug-texinfo/2022-02/msg00000.html
>>>>
>>>> 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 - [email protected] - 0x12DE1598.asc>
>
> Here's an example of how @defline and @linemacro can be used together
> to imitate the format of the numpy documentation at
> https://numpy.org/doc/1.24/reference/generated/numpy.fft.fft.html#numpy.fft.fft
> (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
>
> @defblock
> @defline Function fft.fft (a, n=@code{None}, axis=@code{-1}, norm=@code{None})
> Compute the one-dimensional discrete Fourier Transform.
>
> @defblock
> @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.

OpenPGP_0x0AB0D067012F08C3.asc (application/pgp-keys, 2.8 KB)

OpenPGP_signature (application/pgp-signature, 495 B) - not displayed