Update docs with suggested changes

Tanmay2028 · Tanmay2028 · commit e1af5c1db280 · 2026-01-06T17:05:00.000+01:00
diff --git a/docs/how-tos/pynxtools/ontology-service.md b/docs/how-tos/pynxtools/ontology-service.md
@@ -1,26 +1,31 @@
-# Using ontology service in pynxtools
+# Using the ontology service in pynxtools
 
-!!! info "This is a how-to guide for using the ontology service. If you want to learn more about how `ontology service` works in `pynxtools`, please visit the [explanation](../../learn/pynxtools/ontology-service.md) "
+!!! info "This is a how-to guide for using the ontology service. If you want to learn more about how `ontology service` works in `pynxtools`, please visit the [explanation](../../learn/pynxtools/ontology-service.md)."
 
 ## Prerequisites
 
 - Python 3.10+
-- Install required packages:
-  - `pynxtools` and its dependencies (see [`pyproject.toml`](https://github.com/FAIRmat-NFDI/pynxtools/blob/master/pyproject.toml))
-  - `owlready2`, `pygit2`, `fastapi`, `uvicorn`
-- Ensure the NeXusOntology and definitions submodules are initialized (see [Development guide](../../tutorial/contributing.md#development-installation)).
+- You will first need to install pynxtools and its dependencies (see [pyproject.toml](https://github.com/FAIRmat-NFDI/pynxtools/blob/master/pyproject.toml)), including owlready2, pygit2, fastapi, uvicorn. For more information about the installation, see [installation guide](../../tutorial/installation.md)
+- If you plan to work on `pynxtools` and the ontology service locally, follow the [development guide](../../tutorial/contributing.md). Ensure the NeXusOntology and definitions submodules [are initialized](../../tutorial/contributing.md#development-installation).
 
-## Getting Started
+!!! note "NeXusOntology and definitions submodules"
+    === "Using pynxtools (standard installation)"
+        If you are simply using `pynxtools` as a package, the NeXusOntology and definitions submodules are included automatically during installation. Follow the [installation guide](../../tutorial/installation.md) to get started.
 
-### Importing and Using the Service
+    === "Developing the ontology service"
+        If you are contributing to or developing the ontology service, you need to manually initialize the submodules. See the [development guide](../../tutorial/contributing.md#development-installation) for instructions on setting up the development environment.
+
+## Getting started
+
+### Importing and using the service
 
 The main entry point is the FastAPI app defined in [`pynxtools.nomad.apis.ontology_service`](https://github.com/FAIRmat-NFDI/pynxtools/blob/ontology-service/src/pynxtools/nomad/apis/ontology_service.py). You can import and use the service as follows:
 
 ```python
 from pynxtools.nomad.apis.ontology_service import app, load_ontology, fetch_superclasses
 ```
 
-### Minimal Working Example
+### Minimal working example
 
 You can extract superclasses for a NeXus class using the ontology service's HTTP API endpoint. Here's an example using Python's `requests` library:
 
@@ -46,14 +51,11 @@ When you upload a NeXus file to NOMAD, the ontology service is automatically tri
 
 1. **Triggering**: During normalization, NOMAD reads the `definition__field` from NeXus entry (e.g., `NXmpes_arpes`).
 
-![Processing NeXus files in NOMAD](../../assets/ontology-service-trigger.png){ width="800" }
-![Reading definition field](../../assets/entry_definition__field.png){ width="800" }
+    ![Processing NeXus files in NOMAD](../../assets/ontology-service-trigger.png){ width="800" }
+    ![Reading definition field](../../assets/entry_definition__field.png){ width="800" }
 
 2. **Querying**: The service loads the ontology (or generates it if not already present) and retrieves all superclasses for that application definition.
 
 3. **Storing results**: The retrieved superclasses are stored in `results.eln.methods` in the NOMAD archive.
 
-![Ontology results in NOMAD](../../assets/superclasses_results.png){ width="800" }
-
-!!! info "Further Reading"
-    - [Learn: Understanding the ontology service in pynxtools](../../learn/pynxtools/ontology-service.md)
+    ![Ontology results in NOMAD](../../assets/superclasses_results.png){ width="800" }
diff --git a/docs/index.md b/docs/index.md
@@ -50,7 +50,7 @@ We are offering a small guide to getting started with NeXus, `pynxtools`, and NO
 - [Running `pynxtools` tests in parallel](how-tos/pynxtools/run-tests-in-parallel.md)
 - [Using Python to create NeXus files](how-tos/pynxtools/create-nexus-files-by-python.md)
 - [Validation of NeXus files](how-tos/pynxtools/validate-nexus-files.md)
-- [Use ontology service](how-tos/pynxtools/ontology-service.md)
+- [Use the ontology service](how-tos/pynxtools/ontology-service.md)
 
 </div>
 
@@ -69,7 +69,7 @@ We are offering a small guide to getting started with NeXus, `pynxtools`, and NO
 - [Data conversion in `pynxtools`](learn/pynxtools/dataconverter-and-readers.md)
 - [Validation of NeXus files](learn/pynxtools/nexus-validation.md)
 - [The `MultiFormatReader` as a reader superclass](learn/pynxtools/multi-format-reader.md)
-- [Introduction to ontology service](learn/pynxtools/ontology-service.md)
+- [Introduction to the ontology service](learn/pynxtools/ontology-service.md)
 
 </div>
 <div markdown="block">
diff --git a/docs/learn/pynxtools/ontology-service.md b/docs/learn/pynxtools/ontology-service.md
@@ -1,6 +1,6 @@
 # Understanding the ontology service in pynxtools
 
-!!! info "This is a learn guide for using the ontology service. If you want to learn more about how to use `ontology service` in `pynxtools`, please visit the [explanation](../../how-tos/pynxtools/ontology-service.md) "
+!!! info "This is a learn guide for using the ontology service. If you want to learn more about how to use `ontology service` in `pynxtools`, please visit the [explanation](../../how-tos/pynxtools/ontology-service.md)."
 
 ## Introduction
 
@@ -16,9 +16,9 @@ By using these ontologies, the service maps NeXus application definitions to sta
 
 ## How it fits in pynxtools
 
-This service only operates when `pynxtools` is run within `NOMAD`, exposing ontological data for NeXus Application definitions through a FastAPI interface. It uses NOMAD's configuration to set up the API base path and plugin entry points, then processes NeXus definitions to provide semantic data to users and connected systems.
+The `ontology service` only operates when `pynxtools` is run within `NOMAD`. It is registered as an [`ApiEntryPoint`](https://nomad-lab.eu/prod/v1/docs/reference/config.html#apientrypoint), which allows NOMAD to automatically discover and mount the FastAPI routes at startup. The service exposes [NeXus ontology](https://github.com/nexusformat/NeXusOntology) to users and connected systems.
 
-## Core Concepts
+## Core concepts
 
 - **Ontology**: A formal representation of concepts (classes), relationships, and properties, typically serialized as [OWL](https://www.w3.org/OWL/) files.
 - **Application definition**: A class or term describing an experimental technique in the NeXus (e.g., `NXmpes_arpes`).
@@ -27,24 +27,24 @@ This service only operates when `pynxtools` is run within `NOMAD`, exposing onto
 
 Ontologies are represented as OWL files (e.g., `NeXusOntology_full_<commit>_inferred.owl`) and loaded using `owlready2`.
 
-## Architecture & Design
+## Architecture & design
 
-- **Main Modules**:
-  - `pynxtools.nomad.apis.ontology_service`: FastAPI app, core logic for loading and querying ontologies.
-  - `pynxtools.NeXusOntology.script.generate_ontology`: Generates ontology files from NeXus definitions.
-  - `pynxtools.nomad.schema`: Initializes metainfo and schema integration.
-- **Key Classes/Functions**:
-  - `load_ontology()`: Loads the inferred ontology file.
-  - `fetch_superclasses(ontology, class_name)`: Retrieves superclasses for a given NeXus class.
-  - `ensure_ontology_file()`: Ensures ontology file is present and up-to-date.
-- **Data Flow**:
-  1. On startup, the service verifies whether the inferred ontology file exists; if absent, it runs the reasoner and generates the inferred ontology file.
-  2. Inferred ontology is loaded via `owlready2`.
-  3. API endpoints query this inferred ontology for relationships and metadata.
+- **Main modules**:
+    - `pynxtools.nomad.apis.ontology_service`: FastAPI app, core logic for loading and querying ontologies.
+    - `pynxtools.NeXusOntology.script.generate_ontology`: Generates ontology files from NeXus definitions.
+    - `pynxtools.nomad.schema`: Initializes metainfo and schema integration.
+- **Key classes/functions**:
+    - `load_ontology()`: Loads the inferred ontology file.
+    - `fetch_superclasses(ontology, class_name)`: Retrieves superclasses for a given NeXus class.
+    - `ensure_ontology_file()`: Ensures ontology file is present and up-to-date.
+- **Data flow**:
+    - On startup, the service verifies whether the inferred ontology file exists; if absent, it runs the reasoner and generates the inferred ontology file.
+    - Inferred ontology is loaded via `owlready2`.
+    - API endpoints query this inferred ontology for relationships and metadata.
 
-## Extensibility Points
+## Extensibility points
 
-- Extend FastAPI routes in `ontology_service.py` for new queries.
+- Extend FastAPI routes in [`ontology_service.py`](https://github.com/FAIRmat-NFDI/pynxtools/blob/ontology-service/src/pynxtools/nomad/apis/ontology_service.py) for new queries.
 
 ## Examples
 
