Enable `.. only_in:: sc` to work in all places

[tedmoore]

Currently it seems that the .. only_in:: sc`` functionality only works in the discussion section. It would be wonderful for it to also be available in the :control:` sections to enable something like this:

:control algorithm:

   The feature on which novelty is computed.

   .. only_in:: sc
      
      The argument can be passed as an integer (see table below) which is modulatable, or as one of the following symbols: ``\spectrum``, ``\mfcc``, ``\chroma``, ``\pitch``, or ``\loudness``.

   :enum:

      :0:
         Spectrum – The magnitude of the full spectrum.

      :1:
         MFCC – 13 Mel-Frequency Cepstrum Coefficients.

      :2:
         Chroma – The contour of a 12-band chromagram.

      :3:
         Pitch – The pitch and its confidence.

      :4:
         Loudness – The true peak and loudness.

[weefuzzy]

Hmm. They should work anywhere a rst directive does (i.e. in any of the bits where we parse for rst markup). It could be that the special acrobatics needed cope with enum screw it up.

[tedmoore]

I see. The above didn't work for me but it doesn't seem that necessary for v1 this week so hence just this ticket. At a time in the future I think it will be worth poking at more.

[tremblap]

and now, i have the same issue with .. only_in:: max where I try to add a reference to the refer method for max and pd. I think I might pollute the SC ref for the greater good and maybe we should have a .. not_in:: sc since I need it for both Max and Pd... @tedmoore did you make it work in the end?

(see https://discourse.flucoma.org/t/pure-data-html-documentation-fluid-dataset-refer-message-not-documented/2227/2 for the problem I'm trying to solve)

[weefuzzy]

Shouldn't .. only_in be able to take a list of CCE names? Looks like it from the code. Does .. only_in:: max pd not work for you?

[weefuzzy]

Don't want to add .. not_in:: because implies future knowledge of any additional CCEs that might get added. Could easily violate any principle of least surprise

[tremblap]

at the moment I cannot get only_in:: to work for a full block, like:

.. only_in:: max

:message refer:

   :arg name: The name of the FluidDataSet.

   The object will point to the FluidDataSet named ``name``

I've added it to the source on main without the only_in for now

[weefuzzy]

Yes, we can't break up a reStructuredText field list (which is basically the format of the list of controls, messages etc) with a directive (.. <something>::) AFAIK.

We could look at adding only_in like functionality to individual controls / messages by making the field parsing more sophisticated like :message refer only_in=[max pd]:

[tremblap]

there is a single message like this for now (that was found after years of people using it :) ) so I tried to add that for all. the fun conclusion is that it doesn't add the method at all (I tried locally and pushed on main and re-run all nightlies) - something is going on that I don't understand...

[tedmoore]

I don't think that this was ever resolved (hence it's still open I guess). And looking at what this issues is requesting along with what the NoveltySlice document currently contains it looks like no developments happened.

Regarding the issue filed here, it looks like I just put the "only in sc" note that I wanted into the discussion section (whereonly_in works). This solution feels fine to me for the issue made here. But based on what @tremblap is trying to do for Pd, it sounds like this wouldn't be a valid solution.

[weefuzzy]

Yeah, they're two different things. In your OP, the directive could plausibly be made to work if the description for the control was being parsed with due vigour (which definitely feels like something that should happen, in principle). @tremblap's desire was different, which was to make a whole message / control host-dependent. In his particular case, turned out we could just sneak it into the jinja template instead (which sucks a bit, but it sucks with precedent).