Emmet-Core Docs

.github/workflows/testing.yml

@@ -91,6 +91,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements-docs.txt
+        pip install -e emmet-core/
 
     - name: Build
       run: mkdocs build

docs/core.md

@@ -0,0 +1,15 @@
+# Emmet-Core
+
+The core module defines the data models for the Materials API (MAPI):
+
+::: emmet.core.symmetry
+
+::: emmet.core.structure
+
+::: emmet.core.material
+
+::: emmet.core.thermo
+
+::: emmet.core.provenance
+
+::: emmet.core.polar

docs/packages.md

@@ -0,0 +1,19 @@
+# Packages
+
+`emmet` is a toolkit of packages that are used in conjunction to create the Materials API (MAPI) from raw calculations on disk. The following package make up this toolkit.
+
+## emmet-core
+
+This is the core package for the `emmet` ecosystem. `emmet.core` is where data models are defined. These data models are the most important part of `emmet` since they dictate what all the other packages have to use, serve, or compute.
+
+There is an additional `emmet.stubs` module that provides `pydantic` compatible stubs for various datatypes commonly used in `emmet`. Many of these are from `pymatgen`. These stubs are 100% functional in-place, meaning they can be used as they would be from pymatgen. The stubs provide additional metadata for the models in `emmet` to use for validation and better documentation.
+
+
+## emmet-cli
+
+Many of the operations in `emmet` are complex. These range from backing up calculations, to parsing, to setting of build chains, to starting workflows. Since these processes are pretty standard, the `emmet` ecosystem provides a CLI implemented in `emmet.cli`. This makes managing MAPI much easier.
+
+
+## emmet-builders
+
+The data served via MAPI has to computed via data pipelines. `emmet.builders` defines these operations using the [`maggma`](https://materialsproject.github.io/maggma/) framework to enable well constructed data access, multi- and distributed processing, reporting, and automatic incremental computation.

docs/settings.md

@@ -0,0 +1,18 @@
+# Settings Management
+
+`emmet` has a flexible settings management system based on Pydantic's `BaseSetting`. A core `EmmetSettings` class is used to define a data model for settings. `EmmetSettings` will automatically use the `emmet_config_path` environment variable (defaults to `$HOME/.emmet.json`) to load the settings for the whole `emmet` system. By inheriting from this class, any subpackage automatically gets this core loading feature.
+
+Example:
+``` python
+from pydantic import Field
+from emmet.settings import EmmetSettings
+
+class MySettings(EmmetSettings):
+    my_new_setting: int = Field(3,description = "A custom setting")
+```
+
+Now any instance of `MySettings` will automatically load the configuration file and use that to initialize this setting. Using the magic of `pydantic` `BaseSettings`, these settings can also be set using environment variables prefixed by `EMMET_`.
+
+``` bash
+export EMMET_MY_NEW_SETTING=4
+```

docs/stubs.md

@@ -0,0 +1,3 @@
+# Stubs
+
+`emmet` uses `pydantic` classes to define the data models that get built and dissemenated via the `emmet` toolkit. Many of these datatypes are built in structures in other packages that don't have the full functionality of type hints that `pydantic` would like to use. `emmet.stubs` provides fully functioning stub implementations. These classes can be used just as the original classes with all of their methods and attributes. They provide built in descriptions and schema when these data models are used for the API or validation.

emmet-core/setup.py

@@ -15,7 +15,7 @@
     install_requires=[
         "pymatgen",
         "monty",
-        "pydantic",
+        "pydantic[email]",
         "pybtex",
         "typing-extensions",
         "pymongo",

mkdocs.yml

@@ -7,14 +7,13 @@ theme:
 
 nav:
   - Home: index.md
+  - Packages: packages.md
+  - Settings: settings.md
+  - Stubs: stubs.md
   - Reference:
-      Core:
-        Store: reference/core_store.md
-        Builder: reference/core_builder.md
-        Validator: reference/core_validator.md
-      Stores: reference/stores.md
-      Builders: reference/builders.md
+    - Core: core.md
 
+site_url: https://materialsproject.github.io/emmet/
 repo_url: https://github.com/materialsproject/emmet/
 markdown_extensions:
   - admonition

requirements-docs.txt

@@ -2,4 +2,5 @@ mkdocs==1.1
 mkdocs-material==5.1.0
 mkdocs-material-components==1.10.11
 mkdocs-minify-plugin==0.3.0
-mkdocstrings==0.10.3
+git+git://github.com/pawamoy/pytkdocs.git#egg=pytkdocs
+mkdocstrings==0.11.0