diff --git a/docs/general.md b/docs/general.md
index 90e1a614..f2bd0083 100644
--- a/docs/general.md
+++ b/docs/general.md
@@ -3,9 +3,11 @@
 <!--
 Improve these paragraphs once `Program` and `BaseSimulation` are integrated in `basesections.py`
 --->
-In NOMAD, all the simulation metadata is defined in the `Simulation` section. You can find its Python schema definition in [src/nomad_simulations/general.py](https://github.com/nomad-coe/nomad-simulations/blob/develop/src/nomad_simulations/general.py). This section will appear under the `data` section for the [*archive*](https://nomad-lab.eu/prod/v1/staging/docs/reference/glossary.html#archive) metadata structure of each [*entry*](https://nomad-lab.eu/prod/v1/staging/docs/reference/glossary.html#entry).
+In NOMAD, all the simulation metadata is defined in the `Simulation` section. You can find its Python schema definition in [src/nomad_simulations/schema_packages/general.py](https://github.com/nomad-coe/nomad-simulations/blob/develop/src/nomad_simulations/schema_packages/general.py){:target="_blank"}. This section will appear under the `data` section for the [*archive*](https://nomad-lab.eu/prod/v1/staging/docs/reference/glossary.html#archive){:target="_blank"} metadata structure of each [*entry*](https://nomad-lab.eu/prod/v1/staging/docs/reference/glossary.html#entry){:target="_blank"}.
 
-The `Simulation` section inherits from a _base section_ `BaseSimulation`. In NOMAD, a set of [base sections](https://nomad-lab.eu/prod/v1/staging/docs/howto/customization/base_sections.html) derived from the [Basic Formal Ontology (BFO)](https://basic-formal-ontology.org/) are defined. We used them to define `BaseSimulation` as an [`Activity`](http://purl.obolibrary.org/obo/BFO_0000015). The UML diagram is:
+The `Simulation` section inherits from a _base section_ `BaseSimulation`. In NOMAD, a set of [base sections](https://nomad-lab.eu/prod/v1/staging/docs/howto/customization/base_sections.html){:target="_blank"} derived from the [Basic Formal Ontology (BFO)](https://basic-formal-ontology.org/){:target="_blank"} are defined. We used them to define `BaseSimulation` as an [`Activity`](http://purl.obolibrary.org/obo/BFO_0000015){:target="_blank"}.
+<!-- TODO Fix this and all obo links -->
+The UML diagram is:
 
 <div class="click-zoom">
     <label>
@@ -47,9 +49,9 @@ The `Simulation` base section is composed of 4 main sub-sections:
 4. `Outputs`: contains all the output properties, as well as references to the `ModelSystem` used to obtain such properties. It might also contain information which will populate `ModelSystem` (e.g., atomic occupations, atomic moments, crystal field energies, etc.).
 
 !!! note "Self-consistent steps, SinglePoint entries, and more complex workflows."
-    The minimal unit for storing data in the NOMAD archive is an [*entry*](https://nomad-lab.eu/prod/v1/staging/docs/reference/glossary.html#entry). In the context of simulation data, an entry may contain data from a calculation on an individual system configuration (e.g., a single-point DFT calculation) using **only** the above-mentioned sections of the `Simulation` section. Information from self-consistent iterations to converge properties for this configuration are also contained within these sections.
+    The minimal unit for storing data in the NOMAD archive is an [*entry*](https://nomad-lab.eu/prod/v1/staging/docs/reference/glossary.html#entry){:target="_blank"}. In the context of simulation data, an entry may contain data from a calculation on an individual system configuration (e.g., a single-point DFT calculation) using **only** the above-mentioned sections of the `Simulation` section. Information from self-consistent iterations to converge properties for this configuration are also contained within these sections.
 
-    More complex calculations that involve multiple configurations require the definition of a *workflow* section within the archive. Depending on the situation, the information from individual workflow steps may be stored within a single or multiple entries. For example, for efficiency, the data from workflows involving a large amount of configurations, e.g., molecular dynamics trajectories, are stored within a single entry. Other standard workflows store the single-point data in separate entries, e.g.,  a `GW` calculation is composed of a `DFT SinglePoint` entry and a `GW SinglePoint` entry. Higher-level workflows, which simply connect a series of standard or custom workflows, are typically stored as a separate entry. You can check the [NOMAD simulations workflow schema](https://github.com/nomad-coe/nomad-schema-plugin-simulation-workflow) for more information.
+    More complex calculations that involve multiple configurations require the definition of a *workflow* section within the archive. Depending on the situation, the information from individual workflow steps may be stored within a single or multiple entries. For example, for efficiency, the data from workflows involving a large amount of configurations, e.g., molecular dynamics trajectories, are stored within a single entry. Other standard workflows store the single-point data in separate entries, e.g.,  a `GW` calculation is composed of a `DFT SinglePoint` entry and a `GW SinglePoint` entry. Higher-level workflows, which simply connect a series of standard or custom workflows, are typically stored as a separate entry. You can check the [NOMAD simulations workflow schema](https://github.com/nomad-coe/nomad-schema-plugin-simulation-workflow){:target="_blank"} for more information.
 
 The following schematic represents a simplified representation of the `Simulation` section (note that the arrows here are a simple way of visually defining _inputs_ and _outputs_):
 
@@ -62,7 +64,7 @@ The following schematic represents a simplified representation of the `Simulatio
 
 ### `Program` {#program}
 
-The `Program` base section contains all the information about the program / software / code used to perform the simulation. We consider it to be a [`(Continuant) Entity`](http://purl.obolibrary.org/obo/BFO_0000002) and contained within `BaseSimulation` as a sub-section. The detailed UML diagram is:
+The `Program` base section contains all the information about the program / software / code used to perform the simulation. We consider it to be a [`(Continuant) Entity`](http://purl.obolibrary.org/obo/BFO_0000002){:target="_blank"} and contained within `BaseSimulation` as a sub-section. The detailed UML diagram is:
 
 <div class="click-zoom">
     <label>
@@ -72,7 +74,7 @@ The `Program` base section contains all the information about the program / soft
 </div>
 
 
-When [writing a parser](https://nomad-lab.eu/prod/v1/staging/docs/howto/customization/parsers.html), we recommend to start by instantiating the `Program` section and populating its quantities, in order to get acquainted with the NOMAD parsing infrastructure.
+When [writing a parser](https://nomad-lab.eu/prod/v1/staging/docs/howto/plugins/parsers.html){:target="_blank"}, we recommend to start by instantiating the `Program` section and populating its quantities, in order to get acquainted with the NOMAD parsing infrastructure.
 
 For example, imagine we have a file which we want to parse with the following information:
 ```txt
@@ -81,7 +83,7 @@ For example, imagine we have a file which we want to parse with the following in
 ...
 ```
 
-We can parse the program `name` and `version` by matching the texts (see, e.g., [Wikipedia page for Regular expressions, also called _regex_](https://en.wikipedia.org/wiki/Regular_expression)):
+We can parse the program `name` and `version` by matching the texts (see, e.g., [Wikipedia page for Regular expressions, also called _regex_](https://en.wikipedia.org/wiki/Regular_expression){:target="_blank"}):
 
 ```python
 from nomad.parsing.file_parser import TextParser, Quantity
diff --git a/docs/index.md b/docs/index.md
index 51223b6f..5ccfd0d4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,6 +6,6 @@
 **Welcome to the NOMAD documentation for the Schema developed for Computational Materials Scientists**, where you can find information about how to use the NOMAD schema definition to store the data output by your simulations.
 This project contains all the information about the main base sections and their `SubSections` and `Quantities` relevant for simulations. We propose here a general schema which could then be used as a basis to build more specific schemas.
 
-NOMAD is a free open-source data management platform for Materials Science which follows the F.A.I.R. (Findable, Accessible, Interoperable, and Reusable) principles. This documentation page is a part of the more [general NOMAD documentation](https://nomad-lab.eu/prod/v1/staging/docs/), as well as on the usage of [NOMAD base sections](https://nomad-lab.eu/prod/v1/staging/docs/howto/customization/base_sections.html).
+NOMAD is a free open-source data management platform for Materials Science which follows the F.A.I.R. (Findable, Accessible, Interoperable, and Reusable) principles. This documentation page is a part of the more [general NOMAD documentation](https://nomad-lab.eu/prod/v1/staging/docs/){:target="_blank"}, as well as on the usage of [NOMAD base sections](https://nomad-lab.eu/prod/v1/staging/docs/howto/customization/base_sections.html){:target="_blank"}.
 
-When designing the sections, we follow [SOLID principles](https://www.geeksforgeeks.org/solid-principle-in-programming-understand-with-real-life-examples/) for object-oriented programming. And throughout this documentation, we will use [UML diagrams](https://en.wikipedia.org/wiki/Class_diagram), both in a simplified and in a detailed manner, to draw the schemas relationships.
+When designing the sections, we follow [SOLID principles](https://www.geeksforgeeks.org/solid-principle-in-programming-understand-with-real-life-examples/){:target="_blank"} for object-oriented programming. And throughout this documentation, we will use [UML diagrams](https://en.wikipedia.org/wiki/Class_diagram){:target="_blank"}, both in a simplified and in a detailed manner, to draw the schemas relationships.
diff --git a/docs/model_method/basis_sets.md b/docs/model_method/basis_set.md
similarity index 100%
rename from docs/model_method/basis_sets.md
rename to docs/model_method/basis_set.md
diff --git a/docs/references/atoms_state.md b/docs/references/atoms_state.md
new file mode 100644
index 00000000..2a9592b3
--- /dev/null
+++ b/docs/references/atoms_state.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.atoms_state`
+
+
+::: nomad_simulations.schema_packages.atoms_state
diff --git a/docs/references/basis_set.md b/docs/references/basis_set.md
new file mode 100644
index 00000000..bd4fb49d
--- /dev/null
+++ b/docs/references/basis_set.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.basis_set`
+
+
+::: nomad_simulations.schema_packages.basis_set
diff --git a/docs/references/general.md b/docs/references/general.md
new file mode 100644
index 00000000..7c7d2c0a
--- /dev/null
+++ b/docs/references/general.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.general`
+
+
+::: nomad_simulations.schema_packages.general
diff --git a/docs/references/model_method.md b/docs/references/model_method.md
new file mode 100644
index 00000000..150b113c
--- /dev/null
+++ b/docs/references/model_method.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.model_method`
+
+
+::: nomad_simulations.schema_packages.model_method
diff --git a/docs/references/model_system.md b/docs/references/model_system.md
new file mode 100644
index 00000000..8ed18b32
--- /dev/null
+++ b/docs/references/model_system.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.model_system`
+
+
+::: nomad_simulations.schema_packages.model_system
diff --git a/docs/references/numerical_settings.md b/docs/references/numerical_settings.md
new file mode 100644
index 00000000..07729f26
--- /dev/null
+++ b/docs/references/numerical_settings.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.numerical_settings`
+
+
+::: nomad_simulations.schema_packages.numerical_settings
diff --git a/docs/references/outputs.md b/docs/references/outputs.md
new file mode 100644
index 00000000..ed5a25f6
--- /dev/null
+++ b/docs/references/outputs.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.outputs`
+
+
+::: nomad_simulations.schema_packages.outputs
diff --git a/docs/references/physical_property.md b/docs/references/physical_property.md
new file mode 100644
index 00000000..c1062c90
--- /dev/null
+++ b/docs/references/physical_property.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.physical_property`
+
+
+::: nomad_simulations.schema_packages.physical_property
diff --git a/docs/references/properties/band_gap.md b/docs/references/properties/band_gap.md
new file mode 100644
index 00000000..82326ca3
--- /dev/null
+++ b/docs/references/properties/band_gap.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.band_gap
diff --git a/docs/references/properties/band_structure.md b/docs/references/properties/band_structure.md
new file mode 100644
index 00000000..44b76a12
--- /dev/null
+++ b/docs/references/properties/band_structure.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.band_structure
diff --git a/docs/references/properties/energies.md b/docs/references/properties/energies.md
new file mode 100644
index 00000000..35572b44
--- /dev/null
+++ b/docs/references/properties/energies.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.energies
diff --git a/docs/references/properties/fermi_surface.md b/docs/references/properties/fermi_surface.md
new file mode 100644
index 00000000..574e0873
--- /dev/null
+++ b/docs/references/properties/fermi_surface.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.fermi_surface
diff --git a/docs/references/properties/forces.md b/docs/references/properties/forces.md
new file mode 100644
index 00000000..09ca61e4
--- /dev/null
+++ b/docs/references/properties/forces.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.forces
diff --git a/docs/references/properties/greens_function.md b/docs/references/properties/greens_function.md
new file mode 100644
index 00000000..df1489ab
--- /dev/null
+++ b/docs/references/properties/greens_function.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.greens_function
diff --git a/docs/references/properties/hopping_matrix.md b/docs/references/properties/hopping_matrix.md
new file mode 100644
index 00000000..3fa06581
--- /dev/null
+++ b/docs/references/properties/hopping_matrix.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.hopping_matrix
diff --git a/docs/references/properties/permittivity.md b/docs/references/properties/permittivity.md
new file mode 100644
index 00000000..9aba0500
--- /dev/null
+++ b/docs/references/properties/permittivity.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.permittivity
diff --git a/docs/references/properties/spectral_profile.md b/docs/references/properties/spectral_profile.md
new file mode 100644
index 00000000..dd3fb61b
--- /dev/null
+++ b/docs/references/properties/spectral_profile.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.spectral_profile
diff --git a/docs/references/properties/thermodynamics.md b/docs/references/properties/thermodynamics.md
new file mode 100644
index 00000000..d3ea616d
--- /dev/null
+++ b/docs/references/properties/thermodynamics.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.thermodynamics
diff --git a/docs/references/utils/utils.md b/docs/references/utils/utils.md
new file mode 100644
index 00000000..7f68d24d
--- /dev/null
+++ b/docs/references/utils/utils.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.utils`
+
+
+::: nomad_simulations.schema_packages.utils.utils
diff --git a/docs/references/variables.md b/docs/references/variables.md
new file mode 100644
index 00000000..fe052395
--- /dev/null
+++ b/docs/references/variables.md
@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.variables`
+
+
+::: nomad_simulations.schema_packages.variables
diff --git a/mkdocs.yml b/mkdocs.yml
index 6c9f9ecd..85ec1581 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,10 +8,35 @@ nav:
   - Simulation schema:
     - Overview: general.md
     - ModelSystem: model_system/model_system.md
-    - ModelMethod: model_method/model_method.md
+    - ModelMethod:
+      - ModelMethod: model_method/model_method.md
+      - BasisSet: model_method/basis_set.md
     - Outputs: outputs/outputs.md
   - How to use the Simulation schema: howto_use.md
   - The normalize function: normalize.md
+  - References:
+    - general.py: references/general.md
+    - model_system.py: references/model_system.md
+    - atoms_state.py: references/atoms_state.md
+    - model_method.py: references/model_method.md
+    - numerical_settings.py: references/numerical_settings.md
+    - basis_set.py: references/basis_set.md
+    - outputs.py: references/outputs.md
+    - physical_property.py: references/physical_property.md
+    - variables.py: references/variables.md
+    - Properties:
+      - band_gap.py: references/properties/band_gap.md
+      - band_structure.py: references/properties/band_structure.md
+      - energies.py: references/properties/energies.md
+      - fermi_surface.py: references/properties/fermi_surface.md
+      - forces.py: references/properties/forces.md
+      - greens_function.py: references/properties/greens_function.md
+      - hopping_matrix.py: references/properties/hopping_matrix.md
+      - permittivity.py: references/properties/permittivity.md
+      - spectral_profile.py: references/properties/spectral_profile.md
+      - thermodynamics.py: references/properties/thermodynamics.md
+    - Utils:
+      - utils.py: references/utils/utils.md
   - Contact: contact.md
 theme:
   name: material
@@ -39,6 +64,17 @@ theme:
         name: Switch to light mode
 plugins:
   - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_bases: true  # show inheritance from classes
+            show_source: true  # show source code
+            show_if_no_docstring: true  # show methods if they don't have docstrings
+            show_labels: false  # not showing labels in class attrs
+            docstring_section_style: spacy  # different style for input parameters of methods
+            members_order: source  # order of definitions according to source code
   # - bibtex:
       # bib_file: docs/assets/refs.bib
 markdown_extensions:
@@ -66,6 +102,7 @@ extra_css:
 extra_javascript:
   - 'https://cdnjs.cloudflare.com/ajax/libs/js-yaml/4.1.0/js-yaml.min.js'
   - 'https://unpkg.com/cytoscape@3.19.1/dist/cytoscape.min.js'
+  - 'https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js'
   # - assets/code/parse.js
 extra:
   version: 0.1
diff --git a/requirements_docs.txt b/requirements_docs.txt
index bacf1ed5..c60f1719 100644
--- a/requirements_docs.txt
+++ b/requirements_docs.txt
@@ -2,3 +2,4 @@ mkdocs
 mkdocs-material==8.1.1
 pymdown-extensions
 mkdocs-click
+mkdocstrings-python
\ No newline at end of file