Macros for documentation

[albinahlback]

This would ensure coherent docstrings, and simplify the writing of them.

One downside is that M4 would be required to build the documentation (I didn't manage to do something nice with Python). One will still be able to check whether the documentation is coherent with headers, but one has to run make preprocess when inside doc/ before the actual RST files are ready.

@rburing @edgarcosta @lgoettgens @fredrik-johansson, what are your opinions? The two files you should look at is fmpz.rst.pp and macros.m4 inside doc/source/.

[rburing]

Personally I would macro-fy only the human-readable text description and take the function parameter names as parameters in the macro. That way you can apply the macros also to slightly non-conforming functions, e.g. gr_add which uses gr_srcptr and gr_ptr, and acb_add which takes an additional prec. For example:

.. function:: void fmpz_set(fmpz_t res, const fmpz_t other)
              void fmpz_set_si(fmpz_t res, slong other)
              void fmpz_set_ui(fmpz_t res, ulong other)

describe_set(res, other)

.. function:: void fmpz_zero(fmpz_t res)

describe_zero(res)

Also I would display the parameters like res as monospace text and write e.g.

Sets res equal to poly multiplied by the scalar c.

instead of using formulas, so that the name res can be used without looking strange.

[albinahlback]

Personally I would macro-fy only the human-readable text description and take the function parameter names as parameters in the macro.

I thought about this at first, but this standardizes parameter names. I think it is more clear if the parameter names are set in stone, so that the first input is always X, and the second one is always Y etc.

Also I would display the parameters like res as monospace text

I believe it is important to be consistent with the usage of fonts. One problem is that, typically, they should be typeset with monospace, but that restricts the usage of mathmode. What do you think about this?