document the NeXus files written

[prjemian]

As suggested in https://github.com/nexusformat/definitions/issues/483#issuecomment-521053684, documentation of the NeXus file should be improved. Relevant items for this issue from the NeXus list:

• [x] NXdata documentation about how scan data is to be stored
• [x] documentation for counter_cross_reference
• [x] documentation for positioners_cross_reference
• [x] documentation for the G group
• [x] documentation for the positions group
• [x] documentation for other NXnote groups
• [x] the MCA group (now an NXnote) could be an NXdetector (#190)
• [x] can the positioners fit into NXpositioner (#191)
• [x] clarify what items are defined from SPEC macros
• [x] clarify what items appear on a conditional basis
• [x] how to write and load a custom plugin

[prjemian]

Also, when documenting the G group (and related) the documentation should refer to SPEC's documentation as much as possible and not go beyond detail provided there.

[prjemian]

Plan to delete the NXspecdata contributed definition by end of 2021-12-31.

[prjemian]

• documentation for other NXnote groups

(bluesky_2022_1) prjemian@zap:~/.../prjemian/spec2nexus$ git grep NXnote | grep -v test | grep -v rst
src/spec2nexus/plugins/fallback.py:        nxclass = "NXnote"
src/spec2nexus/plugins/spec_common.py:    * *NXnote* group named **G** in the *NXentry* group, such as */S1/G*
src/spec2nexus/plugins/spec_common.py:                        "NXnote",
src/spec2nexus/plugins/spec_common.py:    * *NXnote* group named **counter_cross_reference** in the *NXentry* group, such as */S1/counter_cross_reference*
src/spec2nexus/plugins/spec_common.py:    * *NXnote* group named **positioners** in the *NXentry* group, such as */S1/positioners*
src/spec2nexus/plugins/spec_common.py:    * *NXnote* group named **positioner_cross_reference** in the *NXentry* group, such as */S1/positioner_cross_reference*
src/spec2nexus/plugins/spec_common.py:            h5parent, "UserReserved", "NXnote", description=desc
src/spec2nexus/plugins/spec_common.py:    * *NXnote* group named **MCA** in the *NXentry* group, such as */S1/MCA*
src/spec2nexus/plugins/spec_common.py:    * *NXnote* group **ROI** in
src/spec2nexus/plugins/spec_common.py:      in *NXnote* group named **MCA**
src/spec2nexus/plugins/unicat.py:    * *NXnote* group named **metadata** below the
src/spec2nexus/plugins/uxml.py:                nxentry, "UXML", "NXnote", desc="UXML metadata"
src/spec2nexus/writer.py:CONTAINER_CLASS = "NXnote"  # any additional freeform information not covered by the other base classes

[prjemian]

This issue is really about documenting the NeXus files that are written. Changing the issue name.

[prjemian]

Existing FIXME & TODO items now:

(bluesky_2022_1) prjemian@zap:~/.../prjemian/spec2nexus$ grep FIXME docs/source/nexus_layout/*.rst
docs/source/nexus_layout/general_tree.rst:FIXME: links have changed direction, new contents added
(bluesky_2022_1) prjemian@zap:~/.../prjemian/spec2nexus$ grep TODO docs/source/nexus_layout/*.rst
docs/source/nexus_layout/mca.rst:TODO: write
docs/source/nexus_layout/mca.rst:TODO: show with one MCA
docs/source/nexus_layout/mca.rst:TODO: show with CALIB
docs/source/nexus_layout/metadata.rst:TODO:  #U and other (#H/#V, #UXML, ...)
docs/source/nexus_layout/sample.rst:TODO
docs/source/nexus_layout/temperature.rst:TODO: ``#X`` (example calib.dat, scan 11) - Temperature Set Point

[prjemian]

• the MCA group (now an NXnote) could be an NXdetector

Not a good fit for the information available now. Will leave support as-is for now.

[prjemian]

Moved the FIXME & TODO list to another issue (for next milestone).