Chapel: Convert spec routines in `..code-block::` format to `..function::` format

[bradcray]

When the spec was converted from latex to rst format, it seems that any function definitions in the were converted to ..code-block:: format. Yet, experimenting, if we make them use the ..function:: format (as with the chpldoc output for routines in module files), the rendering is more consistent across different documentation files. This issue suggests that we should make a sweep of the spec docs to consider cases that could benefit from this format change.

[ben-albrecht]

@bradcray - would you consider this [easy/straightforward]?

[bradcray]

I considered giving it that tag, but then hesitated slightly because I think any changes to the spec should be done with care and didn't want anyone to rush through it haphazardly. With that caveat, I'd be fine with applying the tag to it.

[ben-albrecht]

I considered giving it that tag, but then hesitated slightly because I think any changes to the spec should be done with care and didn't want anyone to rush through it haphazardly.

Agreed. If you think the process is mostly mechanical and it is not tied to the upcoming release, I'd encourage adding the tag. Otherwise, seems fine to leave off. I'll leave it up to your judgement.

[parthsarthiprasad]

@ben-albrecht can I work on this issue? (As much as I am able to understand, We've have to convert ..code-block:: to ..function::)

[ben-albrecht]

@parthsarthiprasad - Absolutely, thanks for your interest!

The spec contents live in doc/rst/language/spec. I think this effort is pretty straightforward as I understand it, where the challenge is ensuring the changes render correctly in HTML after building with make docs.

[parthsarthiprasad]

@bradcray I had doubts regarding how ..function:: works,

• Does it expect a unique name for every function?
• Since function definitions can be overloaded in one file, that can be accepted but having multiple declarations of function with the same name raises an error.

Warning, treated as error:
/home/parth/Desktop/github/chapel/doc/rst/language/spec/classes.rst:33:duplicate object description of syntax, other instance in /home/parth/Desktop/github/chapel/doc/rst/language/spec/arrays.rst, use :noindex: for one of them
make[2]: *** [Makefile.sphinx:72: html-release] Error 2
make[2]: *** [Makefile:125: error_docs] Error 1
make[1]: *** [Makefile:38: docs] Error 2
make: *** [Makefile.devel:26: docs] Error 2

where line line 72 is the first instance of ..function::chapel in classes.rst ; already used in arrays.rst

[bradcray]

@parthsarthiprasad: I'm not particularly expert in this myself, but take a look at the changes to types.rst in the following commit which is a change that I made which motivated me to open this issue: https://github.com/chapel-lang/chapel/pull/15098/files

[parthsarthiprasad]

@bradcray I understood the idea behing the design with proc, adding to style discussion, Was verifying each doc .

Is this the expected design of future block ?
https://chapel-lang.org/docs/master/language/spec/classes.html
Similary for open issues a ..note:: kind of wrapper might feel more suitable?
something like

(I know it's trivial and aesthetic work and probably unnecessary task, but would like to just put it out there)

[bradcray]

@parthsarthiprasad: That's a good question. Let's check with @mppf who did the original conversion of the spec from LaTeX/PDF to the current form. And also @ben-albrecht and @lydia-duncan who've done a fair amount with online documentation to see what they think.

[ben-albrecht]

I think a note is appropriate, maybe like:

.. note::

    *future:*

     Privacy controls for classes ....

There are other types of boxes and extensions to add more box flavors. We could potentially add a custom .. future: box down the road, but let's not worry about that now:

Sphinx colored boxes

[mppf]

Let's check with @mppf who did the original conversion of the spec from LaTeX/PDF to the current form.

The Future and Open Issue blocks ended up the way they are now because that's what the conversion tool gave me. I don't have any objection to changing them to .. note:: blocks but there are quite a few of them...

[ben-albrecht]

but there are quite a few of them...

20 to be exact (assuming they all start with *future*), enough that it would be useful to automate the change rather than change each one manually:

> rg "\*Future\*"

ranges.rst
575:   *Future*.

data-parallelism.rst
478:   *Future*.

arrays.rst
171:   *Future*.
178:   *Future*.

domains.rst
182:   *Future*.
338:   *Future*.

interoperability.rst
18:   *Future*.
88:   *Future*.
100:   *Future*.
161:   *Future*.

classes.rst
66:   *Future*.
151:   *Future*.
439:   *Future*.

memory-consistency-model.rst
524:   *Future*.

task-parallelism-and-synchronization.rst
631:   *Future*.
954:   *Future*.

records.rst
76:   *Future*.

conversions.rst
226:   *Future*.
300:   *Future*.

statements.rst
674:   *Future*.

[lydia-duncan]

I had doubts regarding how ..function:: works,

• Does it expect a unique name for every function?
• Since function definitions can be overloaded in one file, that can be accepted but having multiple declarations of function with the same name raises an error.

Warning, treated as error:
/home/parth/Desktop/github/chapel/doc/rst/language/spec/classes.rst:33:duplicate object description of syntax, other instance in /home/parth/Desktop/github/chapel/doc/rst/language/spec/arrays.rst, use :noindex: for one of them
make[2]: *** [Makefile.sphinx:72: html-release] Error 2
make[2]: *** [Makefile:125: error_docs] Error 1
make[1]: *** [Makefile:38: docs] Error 2
make: *** [Makefile.devel:26: docs] Error 2

where line line 72 is the first instance of ..function::chapel in classes.rst ; already used in arrays.rst

That's interesting. If I remember right, we have multiple functions with the same name in the rest of our documentation (though they don't necessarily all get a link generated for them, which is something we've been meaning to fix, see #5884). This might be something to do with the spec being separated from the rest of the generated documentation in some way - more due to there being multiple names in multiple segments of the docs than multiple names period.

[lydia-duncan]

W.r.t. future blocks - I'd be cautious about adding our own custom boxes, and think that Ben's proposed solution is reasonable