131 add mkdocstrings to docu

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

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.

docs/references/atoms_state.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.atoms_state`
+
+
+::: nomad_simulations.schema_packages.atoms_state

docs/references/basis_set.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.basis_set`
+
+
+::: nomad_simulations.schema_packages.basis_set

docs/references/general.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.general`
+
+
+::: nomad_simulations.schema_packages.general

docs/references/model_method.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.model_method`
+
+
+::: nomad_simulations.schema_packages.model_method

docs/references/model_system.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.model_system`
+
+
+::: nomad_simulations.schema_packages.model_system

docs/references/numerical_settings.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.numerical_settings`
+
+
+::: nomad_simulations.schema_packages.numerical_settings

docs/references/outputs.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.outputs`
+
+
+::: nomad_simulations.schema_packages.outputs

docs/references/physical_property.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.physical_property`
+
+
+::: nomad_simulations.schema_packages.physical_property

docs/references/properties/band_gap.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.band_gap

docs/references/properties/band_structure.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.band_structure

docs/references/properties/energies.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.energies

docs/references/properties/fermi_surface.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.fermi_surface

docs/references/properties/forces.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.forces

docs/references/properties/greens_function.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.greens_function

docs/references/properties/hopping_matrix.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.hopping_matrix

docs/references/properties/permittivity.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.permittivity

docs/references/properties/spectral_profile.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.spectral_profile

docs/references/properties/thermodynamics.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.properties`
+
+
+::: nomad_simulations.schema_packages.properties.thermodynamics

docs/references/utils/utils.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.utils`
+
+
+::: nomad_simulations.schema_packages.utils.utils

docs/references/variables.md

@@ -0,0 +1,5 @@
+
+# `nomad_simulations.schema_packages.variables`
+
+
+::: nomad_simulations.schema_packages.variables

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/[email protected]/dist/cytoscape.min.js'
+  - 'https://unpkg.com/[email protected]/dist/mermaid.min.js'
   # - assets/code/parse.js
 extra:
   version: 0.1

requirements_docs.txt

@@ -2,3 +2,4 @@ mkdocs
 mkdocs-material==8.1.1
 pymdown-extensions
 mkdocs-click
+mkdocstrings-python