UPPERCASE to indicate flexible names

[prjemian]

• close UPPER case notation #1436

editing checklist

• add partial and its description
• Define use of nameType in fields, groups, and attributes
• check the sources for instances where nameType (UPPERCASE flexible names) rules are broken #1490
• Revise a couple NXDL files for development here
• Document all substitutable letters in italics. This will make situations like "Q" and "I" in NXcanSAS more readable, as they will be in non-italics. (Change the Python code that renders the documentation.)
• update the change history with this PR

[prjemian]

Document all substitutable letters in italics

@phyy-nx Do you interpret this to mean Change the Python code that renders the documentation?

Probably will need to add nameType= in some base class just to test any Python code changes. That could be a local modification, to be removed before any merge.

[prjemian]

check the sources for instances where the above rules are broken

I'll list any such instances here and open new issue for each NXDL file separately.

[prjemian]

I'll modify the NXcanSAS and NXdata NXDL files as part of this PR to test documentation of substitutions for the variations of nameType: "specified", "any", and "partial".

[prjemian]

In application definitions, nameType="specified" is assumed throughout, unless provided. In NXcanSAS, in various lines such as

definitions/applications/NXcanSAS.nxdl.xml

Line 144 in ab5e65d

<attribute name="canSAS_class">

the attribute name has upper case but the "SAS" part cannot be replaced by the user.

[prjemian]

The only case in NXcanSAS that requires a non-default nameType is here:

definitions/applications/NXcanSAS.nxdl.xml

Line 1190 in ab5e65d

<group name="TRANSMISSION_SPECTRUM" type="NXdata" minOccurs="0">

This situation is nameType="any", as described in the documentation text.

[prjemian]

@woutdenolf Can you help out with this PR?

I'm stuck on the step Document all substitutable letters in italics. You understand the Python code now better. Can you try this out on NXdata & NXcanSAS? Together, they represent all the nameType= options.

[prjemian]

I added the high priority label since other FAIRmat PRs are waiting on this.

[phyy-nx]

Document all substitutable letters in italics

@phyy-nx Do you interpret this to mean Change the Python code that renders the documentation?

Yup, that's right

[woutdenolf]

I added a commit for: Document all substitutable letters in italics.

I did not find a way to do bolditalic for substitutable characters. Maybe someone can fix that. Currently it is just italic (and bold non-italic for fixed characters).

For example NXdata:

[woutdenolf]

In Nxinstrument I see <group type="NXtransformations" name="DIFFRACTOMETER" />

Is this name variable or fixed?

The current formatting makes it fixed since specified is the default.

[prjemian]

I did not find a way to do bolditalic for substitutable characters

I agree. A quick web search shows bolditalic is not possible in rst.

[prjemian]

Should be: <group type="NXtransformations" name="DIFFRACTOMETER" nameType="any" />

and should be noted on #1490 (not for this PR to resolve)

[lsal93]

I did not find a way to do bolditalic for substitutable characters. Maybe someone can fix that. Currently it is just italic (and bold non-italic for fixed characters).

It should be possible to use html directly, as in this quick google find
https://kallimachos.github.io/rst/bolditalic.html
https://kallimachos.github.io/rst/_sources/bolditalic.rst.txt

I tried the raw html workaround from above link using sphinx 7.3.7 and it seems to work.
.. raw:: html

<b><i>FIELDNAME</i>_scaling_factor</b>

Though perhaps italics only is easier to tell from bold than bolditalics
FIELDNAME_scaling_factor
vs
FIELDNAME_scaling_factor

[sanbrock]

Note that the new convention on substitutable names also effects how the method 'get_first_parent_ref' shall work. It is using get_nx_namefit, but it only checks for UPPERCASE prefixes.
In one of our PRs, we have already implemented an improved version which checks for multiple UPPERCASE runs:
#1428
but this one is not yet checking 'nameType' according to the new rules.

[woutdenolf]

.. raw:: html it needs to be an inline directive though.

[prjemian]

Is there any way to format the entire line in HTML? Might not be if we also want to generate the proper anchors for cross-referencing.

[woutdenolf]

Why would we need the RST formatting in get_first_parent_ref ?

For example

.. _/NXcanSAS/ENTRY/DATA-group:

    *DATA*: (required) :ref:`NXdata` :ref:`⤆ </NXentry/DATA-group>`

/NXentry/DATA-group> does not need formatting (I checked and the link still works as expected)

[woutdenolf]

https://kallimachos.github.io/rst/bolditalic.html

:bolditalic:`This is bold and italic using the :bolditalic: role.`

.. raw:: html

   <b><i>This is bold and italics using raw html.</i></b>

Seems like a sphinx extension? https://github.com/kallimachos/rst/blob/9249dbd4916aece34d27d09fc2c287cadaa2b644/doc/conf.py#L20

This would allow inline bolditalic. I'll try.

https://kallimachos.github.io/chios/bolditalic.html

[woutdenolf]

Seems to work:

An example of the RST formatting of a partial attribute:

  **@**\ :bolditalic:`AXISNAME`\ **_indices**: (optional) :ref:`NX_INT <NX_INT>` 

[prjemian]

https://pypi.org/project/chios/

…

On Wed, Oct 2, 2024, 11:06 AM Wout De Nolf ***@***.***> wrote: Seems to work: image.png (view on web) <https://github.com/user-attachments/assets/a41b8edf-3e74-4c89-98cc-4ad64cbeddb5> An example of the RST formatting of a partial attribute: **@**\ :bolditalic:`AXISNAME`\ **_indices**: (optional) :ref:`NX_INT <NX_INT>` — Reply to this email directly, view it on GitHub <#1485 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARMUMDQXBWOWCI5ITZ4EQDZZQKZ3AVCNFSM6AAAAABPBXI62OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOBZGA2TOMBTGA> . You are receiving this because you were assigned.Message ID: ***@***.***>

[sanbrock]

nameType [specified(default), any, or partial] and its meaning is now handled by the dev_tools/utils/nxdl_utils.py in the PR #1428
Please note that the PR mentioned above is also implementing an example for providing detailed documentation for groups of AppDefs and BaseCalsses while also listing all definitions.

[sanbrock]

We have set up a new PR #1491 which implements handling nameType="partial" in dev_tools, and does not contain the changes in documentation (which was also part of #1428 ).

[woutdenolf]

To be clear, the commits I added to this PR support nameType based RST formatting of the field/attribute/group/link name.

For example

  .. _/NXdata@AXISNAME_indices-attribute:

  .. index:: AXISNAME_indices (file attribute)

  **@**\ :bolditalic:`AXISNAME`\ **_indices**: (optional) :ref:`NX_INT <NX_INT>`

Which results in

Anchor and index is not affected.

[prjemian]

@nexusformat/developers - This is ready for review. We should move promptly since other work (#1419, #1428, #1490, #1491) depends on this PR.

[sanbrock]

Small suggestion for the xsd file.

[prjemian]

We've gained this WARNING (and warnings have been promoted to ERRORs) when building the docs:

2024-10-14T13:48:43.1812615Z /home/runner/work/definitions/definitions/build/manual/source/datarules.rst:75: WARNING: Footnote [#] is not referenced. [ref.footnote]