From 5693820f89b767cefc23502704c0eef0228ffdea Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 29 Apr 2020 10:58:58 -0700 Subject: [PATCH 01/10] use experimental pytkdocs --- requirements-docs.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements-docs.txt b/requirements-docs.txt index a253f3c854..0dd5f2a7f6 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -3,3 +3,4 @@ mkdocs-material==5.1.0 mkdocs-material-components==1.10.11 mkdocs-minify-plugin==0.3.0 mkdocstrings==0.10.3 +-e git@github.com:pawamoy/pytkdocs.git#egg=pytkdocs From 3a22ca0d51deab5fb2d77fb4b8c3412219538417 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 29 Apr 2020 10:59:18 -0700 Subject: [PATCH 02/10] Core docs --- docs/core.md | 5 +++++ mkdocs.yml | 9 ++------- 2 files changed, 7 insertions(+), 7 deletions(-) create mode 100644 docs/core.md diff --git a/docs/core.md b/docs/core.md new file mode 100644 index 0000000000..773b78207d --- /dev/null +++ b/docs/core.md @@ -0,0 +1,5 @@ +# Emmet-Core + +The core module defines the data models for the Materials API (MAPI): + +::: emmet.core.material diff --git a/mkdocs.yml b/mkdocs.yml index 74cac8d5a5..0d00762de5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,13 +7,8 @@ theme: nav: - Home: index.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 + - Packages: packages.md + - Core: core.md repo_url: https://github.com/materialsproject/emmet/ markdown_extensions: From 276fce1918b251979a1d22b09f154b5b5cdafe5e Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 29 Apr 2020 12:30:02 -0700 Subject: [PATCH 03/10] update requirements for git repo --- requirements-docs.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements-docs.txt b/requirements-docs.txt index 0dd5f2a7f6..20dd8f0320 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -2,5 +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 --e git@github.com:pawamoy/pytkdocs.git#egg=pytkdocs +git+git://github.com/pawamoy/pytkdocs.git#egg=pytkdocs +mkdocstrings==0.11.0 From 5cc59915f722306563592b7ea292f1a183adee04 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 29 Apr 2020 12:30:10 -0700 Subject: [PATCH 04/10] add other core documents --- docs/core.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/core.md b/docs/core.md index 773b78207d..03bdeeb1a8 100644 --- a/docs/core.md +++ b/docs/core.md @@ -2,4 +2,14 @@ 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 From 060a6dec99bb50e279b6ffa238f5a3614d086c5e Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 22 Apr 2020 21:48:00 -0700 Subject: [PATCH 05/10] add package description --- docs/packages.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/packages.md diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 0000000000..ed347a7a88 --- /dev/null +++ b/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. From c501803978979e9ea6d0d2db1092d808d668d690 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 29 Apr 2020 21:31:51 -0700 Subject: [PATCH 06/10] Add settings and stubs description --- docs/settings.md | 18 ++++++++++++++++++ docs/stubs.md | 3 +++ 2 files changed, 21 insertions(+) create mode 100644 docs/settings.md create mode 100644 docs/stubs.md diff --git a/docs/settings.md b/docs/settings.md new file mode 100644 index 0000000000..a2c07bfd3a --- /dev/null +++ b/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 +``` diff --git a/docs/stubs.md b/docs/stubs.md new file mode 100644 index 0000000000..f0190466e9 --- /dev/null +++ b/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. From f8b8924272206db3ab594b8e33f9cbef033680c9 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Wed, 29 Apr 2020 21:32:00 -0700 Subject: [PATCH 07/10] New nav structure --- mkdocs.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 0d00762de5..15fd8defb7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,10 @@ theme: nav: - Home: index.md - Packages: packages.md - - Core: core.md + - Settings: settings.md + - Stubs: stubs.md + - Reference: + - Core: core.md repo_url: https://github.com/materialsproject/emmet/ markdown_extensions: From e03abfd36d4697141efe66ea82c25553bcaed7d8 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Sat, 2 May 2020 09:49:33 -0700 Subject: [PATCH 08/10] add site_url --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 15fd8defb7..31545356b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ nav: - Reference: - Core: core.md +site_url: https://materialsproject.github.io/emmet/ repo_url: https://github.com/materialsproject/emmet/ markdown_extensions: - admonition From 2517b328647689ef2f2b2eced58e59c69bbb3c08 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Sat, 2 May 2020 09:53:59 -0700 Subject: [PATCH 09/10] docs: install emmet-core in build script --- .github/workflows/testing.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index 5cbfc11612..11a6249c48 100644 --- a/.github/workflows/testing.yml +++ b/.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 From 82c95607684a00bcb852e3ae441c71fb57d463c5 Mon Sep 17 00:00:00 2001 From: Shyam Dwaraknath Date: Sat, 2 May 2020 10:53:49 -0700 Subject: [PATCH 10/10] install email validator --- emmet-core/setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/emmet-core/setup.py b/emmet-core/setup.py index 61579822b2..4b52341b33 100644 --- a/emmet-core/setup.py +++ b/emmet-core/setup.py @@ -15,7 +15,7 @@ install_requires=[ "pymatgen", "monty", - "pydantic", + "pydantic[email]", "pybtex", "typing-extensions", "pymongo",