From 355e1d318632e06112ead18779d798af1dff2ac3 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Wed, 5 May 2021 09:46:26 -0500 Subject: [PATCH 1/2] MNT #923 comment out --- utils/nxdl2rst.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/utils/nxdl2rst.py b/utils/nxdl2rst.py index c90cdcbc0..d0da4843d 100755 --- a/utils/nxdl2rst.py +++ b/utils/nxdl2rst.py @@ -66,19 +66,19 @@ def sorter(key): ) # fmt: on print(table) - print( - ".. tip::\n" - " Use the reST anchors when writing documentation in\n" - " NXDL source files.\n" - " Since the anchors have no title or caption associated,\n" - " you will need to supply text with the reference, such as::\n\n" - " :ref:`this text will appear `\n\n" - " Since these anchors are absolute references, they may be\n" - " used anywhere in the documentation source \n" - " (that is, within XML ```` structures \n" - " in `.nxdl.xml` files or in ``.rst`` files).\n" - # <doc> - ) + # print( + # ".. tip::\n" + # " Use the reST anchors when writing documentation in\n" + # " NXDL source files.\n" + # " Since the anchors have no title or caption associated,\n" + # " you will need to supply text with the reference, such as::\n\n" + # " :ref:`this text will appear `\n\n" + # " Since these anchors are absolute references, they may be\n" + # " used anywhere in the documentation source \n" + # " (that is, within XML ```` structures \n" + # " in `.nxdl.xml` files or in ``.rst`` files).\n" + # # <doc> + # ) def fmtTyp( node ): From fb97d1460f6e933339a6f1d7e8dcd4af22660e01 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Wed, 5 May 2021 10:06:19 -0500 Subject: [PATCH 2/2] MNT #923 move the tip to NXDL chapter --- manual/source/nxdl.rst | 16 ++++++++++++++++ utils/nxdl2rst.py | 13 ------------- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/manual/source/nxdl.rst b/manual/source/nxdl.rst index 6f0ebdad8..fc8ed8328 100644 --- a/manual/source/nxdl.rst +++ b/manual/source/nxdl.rst @@ -76,6 +76,22 @@ to validate NeXus data files. In fact, all of the tables in the :ref:`Class Definitions ` Chapter have been generated directly from the NXDL files. +.. sidebar:: Writing references and anchors in the documentation. + + .. tip:: + + Use the reST anchors when writing documentation in + NXDL source files. + Since the anchors have no title or caption associated, + you will need to supply text with the reference, such as:: + + :ref:`this text will appear ` + + Since these anchors are absolute references, they may be + used anywhere in the documentation source + (that is, within XML ```` structures + in `.nxdl.xml` files or in ``.rst`` files). + The language of NXDL files is intentionally quite small, to provide only that which is necessary to describe scientific data structures (or to establish the diff --git a/utils/nxdl2rst.py b/utils/nxdl2rst.py index d0da4843d..4b1c8c68d 100755 --- a/utils/nxdl2rst.py +++ b/utils/nxdl2rst.py @@ -66,19 +66,6 @@ def sorter(key): ) # fmt: on print(table) - # print( - # ".. tip::\n" - # " Use the reST anchors when writing documentation in\n" - # " NXDL source files.\n" - # " Since the anchors have no title or caption associated,\n" - # " you will need to supply text with the reference, such as::\n\n" - # " :ref:`this text will appear `\n\n" - # " Since these anchors are absolute references, they may be\n" - # " used anywhere in the documentation source \n" - # " (that is, within XML ```` structures \n" - # " in `.nxdl.xml` files or in ``.rst`` files).\n" - # # <doc> - # ) def fmtTyp( node ):