Implementation of MK docs. #33

RubelMozumder · 2024-04-29T14:02:55Z

No description provided.

lukaspie · 2024-06-03T07:29:07Z

pyproject.toml

@@ -43,6 +43,12 @@ dev = [
    "pre-commit",
    "types-pyyaml",
    "lxml-stubs",
+    "mkdocs",
+    # Mkdocs and the related plugins
+    "mkdocs-mermaid2-plugin"


Suggested change

"mkdocs-mermaid2-plugin"

"mkdocs-mermaid2-plugin",

lukaspie

Initial round of review, there are many places that could be improved. Would also be nice to improve the style a bit to be closer to the style of the documentation of our other tools.

lukaspie · 2025-02-05T15:12:27Z

docs/explanations.md

@@ -0,0 +1,223 @@
+# Motivation
+
+The NeXus data format, described by the NeXus Definition Language (NXDL), represents a concerted effort aimed at facilitating data exchange within scientific communities, particularly among those engaged in neutron, X-ray, and muon research [J. Appl. Cryst. (2015). 48, 301-305](https://doi.org/10.1107/S1600576714027575). The data format is also being used by the material science community under the project [NeXus-FAIRmat](https://fairmat-nfdi.github.io/nexus_definitions/) supporting FAIR (Findable, Accessible, Interoperable and Reuseable) data principle. It serves as a standardized framework for both data exchange and storage. At its core, the NeXus Definition Language (NXDL) functions as the cornerstone through which scientists delineate the nomenclature and organizational structure of information within NeXus data files, tailored to specific scientific techniques.


Suggested change

The NeXus data format, described by the NeXus Definition Language (NXDL), represents a concerted effort aimed at facilitating data exchange within scientific communities, particularly among those engaged in neutron, X-ray, and muon research [J. Appl. Cryst. (2015). 48, 301-305](https://doi.org/10.1107/S1600576714027575). The data format is also being used by the material science community under the project [NeXus-FAIRmat](https://fairmat-nfdi.github.io/nexus_definitions/) supporting FAIR (Findable, Accessible, Interoperable and Reuseable) data principle. It serves as a standardized framework for both data exchange and storage. At its core, the NeXus Definition Language (NXDL) functions as the cornerstone through which scientists delineate the nomenclature and organizational structure of information within NeXus data files, tailored to specific scientific techniques.

The NeXus data format, described by the NeXus Definition Language (NXDL), represents a concerted effort aimed at facilitating data exchange within scientific communities, particularly among those engaged in neutron, X-ray, and muon research [J. Appl. Cryst. (2015). 48, 301-305](https://doi.org/10.1107/S1600576714027575). The data format is also being used by the material science community under the project [NeXus-FAIRmat](https://fairmat-nfdi.github.io/nexus_definitions/) supporting FAIR (Findable, Accessible, Interoperable and Reuseable) data principles. It serves as a standardized framework for both data exchange and storage. At its core, the NeXus Definition Language (NXDL) functions as the cornerstone through which scientists delineate the nomenclature and organizational structure of information within NeXus data files, tailored to specific scientific techniques.

lukaspie · 2025-02-05T15:14:02Z

docs/explanations.md

+
+To expedite the schema development process, we have introduced the use of Yet Another Markup Language ([YAML](https://yaml.org/)), which provides a syntax or style specifically tailored for defining scientific domain-driven schemas with NXDL. One significant advantage of YAML over XML is its indentation-driven approach, which eliminates the need for starting and ending tags for each entity within the schema. The `YAML` format results in a reduction of NXDL keyword repetition and allows for a intuitive grasp with object oriented programing domain, such as class inheritance. These benefits are attained without compromising the integrity of the original NeXus schema, which is traditionally expressed in XML format.
+
+The `YAML` format, while not yet an official version of NeXus application definitions or base classes, necessitates a method for transcoding it into `XML`. The [nyaml](https://github.com/FAIRmat-NFDI/nyaml/tree/main) Python package serves as a converter tool designed specifically for this purpose. It enables the conversion of NXDL from `YAML` format to `XML`, thereby enhancing the capability of NeXus schema developers to incorporate domain-specific scientific knowledge into the schema. Furthermore, the tool offers the flexibility to extend existing NeXus schemas in XML by facilitating conversion back and forth between the two formats. It is important to note that here we do not introduce NeXus data objects, terms, or types, which are fundamental for writing base class schemas or application definition schemas. For individuals new to NeXus, we refer to the official NeXus site at NeXus [official site](https://www.nexusformat.org/).


Suggested change

The `YAML` format, while not yet an official version of NeXus application definitions or base classes, necessitates a method for transcoding it into `XML`. The [nyaml](https://github.com/FAIRmat-NFDI/nyaml/tree/main) Python package serves as a converter tool designed specifically for this purpose. It enables the conversion of NXDL from `YAML` format to `XML`, thereby enhancing the capability of NeXus schema developers to incorporate domain-specific scientific knowledge into the schema. Furthermore, the tool offers the flexibility to extend existing NeXus schemas in XML by facilitating conversion back and forth between the two formats. It is important to note that here we do not introduce NeXus data objects, terms, or types, which are fundamental for writing base class schemas or application definition schemas. For individuals new to NeXus, we refer to the official NeXus site at NeXus [official site](https://www.nexusformat.org/).

The `YAML` format, while not yet an official version of NeXus application definitions or base classes, necessitates a method for transcoding it into `XML`. The [nyaml](https://github.com/FAIRmat-NFDI/nyaml/tree/main) Python package serves as a converter tool designed specifically for this purpose. It enables the conversion of NXDL from `YAML` format to `XML`, thereby enhancing the capability of NeXus schema developers to incorporate domain-specific scientific knowledge into the schema. Furthermore, the tool offers the flexibility to extend existing NeXus schemas in XML by facilitating conversion back and forth between the two formats. It is important to note that here we do not introduce NeXus data objects, terms, or types, which are fundamental for writing base class schemas or application definition schemas. For individuals new to NeXus, we refer to the [official NeXus site](https://www.nexusformat.org/).

lukaspie · 2025-02-05T15:16:15Z

docs/index.md

+
+Tutorials to write different parts and a full NeXus application or base class
+
+- [Tutorials to write NeXus definition in YAML](tutorials.md)


Suggested change

- [Tutorials to write NeXus definition in YAML](tutorials.md)

- [Tutorials for writing NeXus definition in YAML](tutorials.md)

lukaspie · 2025-02-05T15:16:45Z

docs/index.md

+An introduction to NeXus and its design principles.
+
+- [An introduction to NeXus](https://manual.nexusformat.org/index.html)
+- [Motivation for NYAML tool](explanations.md)


Suggested change

- [Motivation for NYAML tool](explanations.md)

- [Explanation of the nyaml tool](explanations.md)

lukaspie · 2025-02-05T15:18:42Z

docs/index.md

+### Reference
+Relavent references that supported to develop this tool:
+- [NYAML GitHub repository](https://github.com/FAIRmat-NFDI/nyaml)
+- [FAIRmat-NeXus website](https://fairmat-experimental.github.io/nexus-fairmat-proposal/)
+- [FAIRmat-NeXus GitHub repository](https://github.com/FAIRmat-NFDI/nexus_definitions)
+- [Official werbsite for NeXus](https://manual.nexusformat.org/index.html)
+
+- [NYAML developed under project FAIRmat-NFDI](https://github.com/FAIRmat-NFDI)
+- [National Research Data Infrastructure (NFDI) funded FAIRmat-NFDI](https://www.nfdi.de/?lang=en)
+</div>
+</div>


Suggested change

### Reference

Relavent references that supported to develop this tool:

- [NYAML GitHub repository](https://github.com/FAIRmat-NFDI/nyaml)

- [FAIRmat-NeXus website](https://fairmat-experimental.github.io/nexus-fairmat-proposal/)

- [FAIRmat-NeXus GitHub repository](https://github.com/FAIRmat-NFDI/nexus_definitions)

- [Official werbsite for NeXus](https://manual.nexusformat.org/index.html)

- [NYAML developed under project FAIRmat-NFDI](https://github.com/FAIRmat-NFDI)

- [National Research Data Infrastructure (NFDI) funded FAIRmat-NFDI](https://www.nfdi.de/?lang=en)

</div>

</div>

### References

- [NYAML GitHub repository](https://github.com/FAIRmat-NFDI/nyaml)

- [FAIRmat-NeXus website](https://fairmat-experimental.github.io/nexus-fairmat-proposal/)

- [FAIRmat-NeXus GitHub repository](https://github.com/FAIRmat-NFDI/nexus_definitions)

- [Official NeXus website](https://manual.nexusformat.org/index.html)

</div>

</div>

<h2>Project and community</h2>

Any questions or suggestions? [Get in touch!](https://www.fair-di.eu/fairmat/about-fairmat/team-fairmat)

[The work is funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) - 460197019 (FAIRmat).](https://gepris.dfg.de/gepris/projekt/460197019?language=en)

lukaspie · 2025-02-05T15:40:59Z

docs/tutorials.md

@@ -0,0 +1,185 @@
+# Tutorials
+This tutorial will explain different keywords, terms and rules from the prespective of YAML format of the NeXus schema.


Suggested change

This tutorial will explain different keywords, terms and rules from the prespective of YAML format of the NeXus schema.

This tutorial will explain different keywords, terms, and rules from the perspective of YAML format of the NeXus schema.

Honestly, this is not a tutorial. It should rather go to explanations.

lukaspie · 2025-02-05T15:41:58Z

docs/tutorials.md

+
+Descriptive information about NeXus groups is encapsulated within the `doc` child of the respective group. It is important to note that the group annotation of `source_TYPE(NXsource)` or `(NXsource)source_TYPE` signifies the encapsulation of the group's `name` as `source_TYPE` and its type as `NXsource` base class. Notably, the order between `name` and `type` within the XML element must be inverted such two different syntax.
+
+Furthermore, the uppercase part of the group's name can be dynamically overwritten, allowing for the instantiation of multiple instances. For example, `source_electric` and `source_magnetic` can coexist from `NXsource`. It is essential to adhere to the uppercase dynamic rules for NeXus groups, fields, and attributes.


This is now covered by nameType=partial, the documentation here should be updated.

lukaspie · 2025-02-05T15:44:00Z

docs/tutorials.md

+### NeXus Choice
+NeXus `choice` concept is designed to choose a concept from a number of concepts of the same kind (e.g., a NeXus field). The `choice` options allows for defining a scientific concept in several modes for different situations (e.g., for different instrument configurations or measurement modes).
+
+**NeXus choice in YAML format**


This doesn't work yet, see #23.

So, I don't think we should mention it here yet.

lukaspie · 2025-02-05T15:44:26Z

docs/tutorials.md

+  \@version:
+  enumeration: [NXmpes]
+```
+In the example the valid value for NeXus field `definition` is `NXmpes`.


Suggested change

In the example the valid value for NeXus field `definition` is `NXmpes`.

In the example, the only valid value for NeXus field `definition` is `NXmpes`.

lukaspie · 2025-02-05T15:44:44Z

docs/tutorials.md

+In the example the valid value for NeXus field `definition` is `NXmpes`.
+
+### Keyword `xref`
+The `xref` keyword (which can only inside the keyword `doc`) is used to refer any other ontology or any other standard such `ISO`. The `xref` in the example `doc` will reflect the information inside the XML `doc`. Note that the `xref` keyword is only available in the `YAML` representation and will be transformed into its textual representation inside the `doc` text in `XML`.


Suggested change

The `xref` keyword (which can only inside the keyword `doc`) is used to refer any other ontology or any other standard such `ISO`. The `xref` in the example `doc` will reflect the information inside the XML `doc`. Note that the `xref` keyword is only available in the `YAML` representation and will be transformed into its textual representation inside the `doc` text in `XML`.

The `xref` keyword (which can only be used inside the keyword `doc`) is used to refer any other ontology or any other standard such `ISO`. The `xref` in the example `doc` will reflect the information inside the XML `doc`. Note that the `xref` keyword is only available in the `YAML` representation and will be transformed into its textual representation inside the `doc` text in `XML`.

RubelMozumder added 5 commits April 29, 2024 16:07

add docs dir, rename READEME to index.

101e5fc

Inclusing Structure of the mk docs.

194c653

update pyproject.

b43c1be

removing other empty md files from docs.

f1aaf76

commenting the other pages from mkdocs.yml

90dfcee

RubelMozumder force-pushed the MyDoc branch from e45c09f to 90dfcee Compare April 29, 2024 14:08

RubelMozumder added 5 commits May 3, 2024 09:01

First step for mydocs.

c9ee29f

Docs v1.

a51be15

v2

6e7946d

v3

14eeb8c

Including mkdocs.yml

278d0f1

lukaspie reviewed Jun 3, 2024

View reviewed changes

lukaspie requested changes Feb 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implementation of MK docs. #33

Implementation of MK docs. #33

RubelMozumder commented Apr 29, 2024

lukaspie Jun 3, 2024

lukaspie left a comment

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

lukaspie Feb 5, 2025

		@@ -0,0 +1,223 @@
		# Motivation

		The NeXus data format, described by the NeXus Definition Language (NXDL), represents a concerted effort aimed at facilitating data exchange within scientific communities, particularly among those engaged in neutron, X-ray, and muon research [J. Appl. Cryst. (2015). 48, 301-305](https://doi.org/10.1107/S1600576714027575). The data format is also being used by the material science community under the project [NeXus-FAIRmat](https://fairmat-nfdi.github.io/nexus_definitions/) supporting FAIR (Findable, Accessible, Interoperable and Reuseable) data principle. It serves as a standardized framework for both data exchange and storage. At its core, the NeXus Definition Language (NXDL) functions as the cornerstone through which scientists delineate the nomenclature and organizational structure of information within NeXus data files, tailored to specific scientific techniques.


		To expedite the schema development process, we have introduced the use of Yet Another Markup Language ([YAML](https://yaml.org/)), which provides a syntax or style specifically tailored for defining scientific domain-driven schemas with NXDL. One significant advantage of YAML over XML is its indentation-driven approach, which eliminates the need for starting and ending tags for each entity within the schema. The `YAML` format results in a reduction of NXDL keyword repetition and allows for a intuitive grasp with object oriented programing domain, such as class inheritance. These benefits are attained without compromising the integrity of the original NeXus schema, which is traditionally expressed in XML format.

		The `YAML` format, while not yet an official version of NeXus application definitions or base classes, necessitates a method for transcoding it into `XML`. The [nyaml](https://github.com/FAIRmat-NFDI/nyaml/tree/main) Python package serves as a converter tool designed specifically for this purpose. It enables the conversion of NXDL from `YAML` format to `XML`, thereby enhancing the capability of NeXus schema developers to incorporate domain-specific scientific knowledge into the schema. Furthermore, the tool offers the flexibility to extend existing NeXus schemas in XML by facilitating conversion back and forth between the two formats. It is important to note that here we do not introduce NeXus data objects, terms, or types, which are fundamental for writing base class schemas or application definition schemas. For individuals new to NeXus, we refer to the official NeXus site at NeXus [official site](https://www.nexusformat.org/).


		Tutorials to write different parts and a full NeXus application or base class

		- [Tutorials to write NeXus definition in YAML](tutorials.md)

	- [Tutorials to write NeXus definition in YAML](tutorials.md)
	- [Tutorials for writing NeXus definition in YAML](tutorials.md)

	- [Motivation for NYAML tool](explanations.md)
	- [Explanation of the nyaml tool](explanations.md)

		@@ -0,0 +1,185 @@
		# Tutorials
		This tutorial will explain different keywords, terms and rules from the prespective of YAML format of the NeXus schema.


		Descriptive information about NeXus groups is encapsulated within the `doc` child of the respective group. It is important to note that the group annotation of `source_TYPE(NXsource)` or `(NXsource)source_TYPE` signifies the encapsulation of the group's `name` as `source_TYPE` and its type as `NXsource` base class. Notably, the order between `name` and `type` within the XML element must be inverted such two different syntax.

		Furthermore, the uppercase part of the group's name can be dynamically overwritten, allowing for the instantiation of multiple instances. For example, `source_electric` and `source_magnetic` can coexist from `NXsource`. It is essential to adhere to the uppercase dynamic rules for NeXus groups, fields, and attributes.

	In the example the valid value for NeXus field `definition` is `NXmpes`.
	In the example, the only valid value for NeXus field `definition` is `NXmpes`.

	The `xref` keyword (which can only inside the keyword `doc`) is used to refer any other ontology or any other standard such `ISO`. The `xref` in the example `doc` will reflect the information inside the XML `doc`. Note that the `xref` keyword is only available in the `YAML` representation and will be transformed into its textual representation inside the `doc` text in `XML`.
	The `xref` keyword (which can only be used inside the keyword `doc`) is used to refer any other ontology or any other standard such `ISO`. The `xref` in the example `doc` will reflect the information inside the XML `doc`. Note that the `xref` keyword is only available in the `YAML` representation and will be transformed into its textual representation inside the `doc` text in `XML`.

Implementation of MK docs. #33

Are you sure you want to change the base?

Implementation of MK docs. #33

Conversation

RubelMozumder commented Apr 29, 2024

Choose a reason for hiding this comment

lukaspie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment