mkdocs.yml

site_name: Documentation
site_description: |
  The documentation for NOMAD v1.
site_author: The NOMAD Authors
repo_url: https://github.com/nomad-coe/nomad
edit_uri: ""
nav:
  - Home: index.md
  - Tutorial:
      - Overview: tutorial/overview.md
      - Upload and publish data:
          - With the GUI: tutorial/upload_publish.md
          - Programmatically: tutorial/upload_publish_api.md
      - Explore data: tutorial/explore.md
      - Use NOMAD as an ELN:
          - Built-in ELN templates: tutorial/eln/built_in_templates.md
          - Custom ELN with YAML: tutorial/eln/custom_eln_yaml.md
          - Tabular Parser for ELN: tutorial/eln/tabular_parser_yaml.md
      - Manage workflows and projects: tutorial/workflows_projects.md
      - Develop a NOMAD plugin: tutorial/develop_plugin.md
  - How-to guides:
      - Overview: howto/overview.md
      - Manage and find data:
          - With the GUI:
              - Upload and publish data: howto/manage/gui/upload.md
              - Enter data with ELNs: howto/manage/gui/eln.md
              - Analyze data in NORTH: howto/manage/gui/north.md # TODO rename depending on how-to content
              - Create custom workflows: howto/manage/gui/workflows.md
              - Write a YAML schema package: howto/manage/gui/yaml.md # TODO consolidate with parts of the next 2 pages
              - Create custom ELNs: howto/manage/gui/elns.md
              - Parse tabular data: howto/manage/gui/tabular.md
          - Programmatically:
              # - Install nomad-lab: howto/programmatic/pythonlib.md # TODO Integrate into "Use the API"
              - API Overview: howto/manage/program/api.md # TODO separate into How-to and Explanation/Reference
              - Programmatic authentication: howto/manage/program/auth.md
              - Download data: howto/manage/program/download.md
              - Publish data using Python: howto/manage/program/publish_python.md
              - Access processed data: howto/manage/program/archive_query.md
              - Transform data: howto/manage/program/json_transformer.md
              - Make graph-API calls: howto/manage/program/graph_api.md # TODO consolidate into a single page with supporting explanation/reference material
      - Develop plugins:
          - Plugins Overview: howto/plugins/plugins.md # TODO split former Introduction to plugins into short guiding overview + explanation page
          # - Set up a development environment: howto/plugins/setup.md # TODO distro-dev setup + best practices
          - Entry point types:
              - Actions: howto/plugins/types/actions.md
              - APIs: howto/plugins/types/apis.md
              - Apps: howto/plugins/types/apps.md
              - Example uploads: howto/plugins/types/example_uploads.md
              - Normalizers: howto/plugins/types/normalizers.md
              - NORTH tools: howto/plugins/types/north_tools.md
              - Parsers: howto/plugins/types/parsers.md
              - Schemas: howto/plugins/types/schema_packages.md
          - Built-in tools:
              - Work with units: howto/plugins/tools/units.md
              - Handle large data: howto/plugins/tools/hdf5.md
              - Parse efficiently: howto/plugins/tools/mapping_parser.md # TODO Add clearly scope at the top of this page
      - Host a NOMAD Oasis:
          - Install: howto/oasis/install.md # TODO Would explain what a NOMAD installation means, contains links to `nomad-distro-template`+`nomad-distro-dev`, also contains a small section on the Python library
          - Configure: howto/oasis/configure.md
          - Deploy: howto/oasis/deploy.md
          - Update: howto/oasis/update.md
          - Administer: howto/oasis/administer.md
          - Secure: howto/oasis/secure.md
          - Troubleshoot: howto/oasis/troubleshoot.md
      - Develop the core software: # TODO strip down to only nomad-lab-specific development
          - Get started: howto/develop/setup.md
          - Navigate the code: howto/develop/code.md
          - Contribute: howto/develop/contrib.md
          - Write a normalizer: howto/develop/normalizing.md
          - Extend the search: howto/develop/search.md
          - Make a release: howto/develop/release.md
  - Domain-specific examples: # TODO decide uniform structure for navigation to plugins/plugin-docs
      - Overview: examples/overview.md
      - Computational data:
          - Basics: examples/computational_data/basics.md
          - MetaInfo: examples/computational_data/metainfo.md
          - Schema plugins: examples/computational_data/schema_plugins.md
          - Parser plugins: examples/computational_data/parser_plugins.md
          - FAQs: examples/computational_data/faqs.md
      - Experimental data:
          - Electron microscopy: examples/experiment_data/em.md
          - Photoemission spectroscopy: examples/experiment_data/mpes.md
          - X-ray photoemission spectroscopy: examples/experiment_data/xps.md
          - Optical spectroscopy: examples/experiment_data/opt.md
          - Atom probe tomography: examples/experiment_data/apm.md
          - Scanning probe microscopy: examples/experiment_data/spm.md
          - pynxtools: examples/experiment_data/pynxtools.md
      - Use cases:
          - Catalysis APP: examples/use_cases/catalysis_app.md
          - NEB workflows: examples/use_cases/neb_workflows.md
        # - NOMAD-supported plugins:
        # - Databases for specific research topics:
  - Explanation:
      # - Overview: explanation/overview.md # TODO add guide, organization of sub-pages?
      - From files to data: explanation/basics.md
      - Data structure: explanation/data.md
      - Base sections: explanation/base_sections.md # TODO rewrite as explanation
      - Processing: explanation/processing.md
      - Architecture: explanation/architecture.md
      - Workflows: explanation/workflows.md
      - Plugins: explanation/plugin_system.md
      - Federation and Oasis: explanation/oasis.md
      - Authentication and authorization: explanation/auth.md
      - NORTH: explanation/north.md
  - Reference:
      # - Overview: reference/overview.md # TODO
      # - reference/metainfo.md # TODO This file no longer exists ... was it lost somehow?
      - reference/config.md
      - reference/annotations.md
      - reference/basesections.md
      - reference/cli.md
      - reference/plugins.md
      - reference/parsers.md
      - reference/code_guidelines.md
      - reference/glossary.md
      - reference/tutorials.md
theme:
  name: material
  palette:
    # 1. Light
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # 2. Dark
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to system preference
    # 3. Auto
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode
  font:
    text: "Titillium Web"
  favicon: assets/favicon.png
  features:
    - navigation.path
    - navigation.footer
    - navigation.top
    - content.code.copy
    - content.code.annotate
  custom_dir: overrides
  icon:
    logo: nomad/nomad-logo-unfilled
    repo: fontawesome/brands/github
# repo_url: https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR/
markdown_extensions:
  - attr_list
  - md_in_html
  - admonition
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - mkdocs-click
  - pymdownx.extra
  - toc:
      permalink: True
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

extra:
  generator: false
  homepage: https://nomad-lab.eu
use_directory_urls: false
plugins:
  - search
  - macros:
      module_name: src/nomad_docs/__init__
  - redirects:
      redirect_maps:
        "develop/gitlab.md": "howto/develop/contrib.md"
  - glightbox
  # - git-revision-date-localized
  # TODO Fix error in pipeline when this plugin is included
  # (with 'mkdocs-git-revision-date-localized-plugin==1.2.1' in pyproject.toml)
  # see pipeline error here: https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR/-/jobs/2473217
extra_css:
  - stylesheets/extra.css
extra_javascript:
  - create-image-sliders.js
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js