🍎 update custom app guides

CHANGELOG.md

@@ -31,6 +31,7 @@ There is one key exception to the rules above -- and that is with `MAJOR`=0 rele
 - NEB workflow now accepts parameters to tune how distinct pathways are determined, including the max pathway length and cutoffs at 1D percolation.
 - add `MatplotlibFigure` and `PlotlyFigure` classes to help with writing output files and also implementing these figures in the website UI
 - update website to include workflow calculator types and add API links
+- custom projects and database tables are now registered with Simmate and a intro guide has been added
 
 **Refactors**
 - the `website.core_components.filters` module has been absorbed into the `DatabaseTable` class/module

docs/getting_started/custom_tables_and_apps/create_a_custom_app.md

@@ -1,16 +1,152 @@
+-------------------------------------------------------------------------------
 
-# Creating a new project
+# Creating new project files
 
-1. Let's create a project named `my_new_project`. To do this, navigate to a folder where you'd like to store your code and run...
+1. To create a new project, navigate to a folder where you'd like to store your code and run...
 ``` bash
-simmate start-project my_new_project
+simmate start-project
 ```
 
-2. You will see a new folder named "my_new_project" which you can switch into.
+2. Doublecheck that you see a new folder named `my_new_project`. Open it up and you should see a series of new files:
+```
+my_new_project/
+├── pyproject.toml
+├── README.md
+└── example_app
+    ├── __init__.py
+    ├── apps.py
+    ├── models.py
+    ├── tests.py
+    ├── urls.py
+    ├── views.py
+    └── workflows.py
+```
+
+3. Make note that we have a folder named `example_app`. This is where our code will go. You can have as many app folders as you'd like (and in **extreme** scenarios even have apps within other apps).
+
+-------------------------------------------------------------------------------
+
+## Name our project and app
+
+!!! danger
+    One you choose a name, stick with it. Changing your project name or app name after it has
+    been installed can lead your code failing with `ModuleNotFound` errors.
+
+!!! tip
+    This step is optional and where many mistakes happen. If you run into errors below, try restarting your project from scratch and leaving the default app names.
+
+** Name the project **
+
+1. Rename your folder from "my_new_project" to a name of your choosing. Try to follow python conventions and keep your project name all lowercase and connected with underscores. For example, `warren_lab` or `scotts_project` are good project names.
+
+2. Open the file `new_project_project/pyproject.toml` and change the name here as well.
+``` toml
+[project]
+name = "my_simmate_project"  # <--- update with your new name
+```
+
+!!! note
+    We will explain these files in a later section. For now, just stick to renaming!
+
+** Name the app **
+
+1. Decide on how your code should be imported. For example, you may want your workflows to be loaded like so:
+``` python
+from my_app.workflows import Example__Workflow__Settings
+```
+
+2. Take the first part of this (`my_app`) and rename the `example_app` folder to match this. The python conventions (described above) also apply here. For example, `simmate_abinit` or `simmate_clease` are informative and good project names. These let the user know what's in your app and they're easy to remember. Here's how they would work:
+``` python
+from simmate_clease.workflows import ClusterExpansion__Clease__BasicSettings
+```
+
+3. Open the file `example_app/apps.py` and rename the class AND name property to match your app name.
+``` python
+from django.apps import AppConfig
+
+class SimmateCleaseConfig(AppConfig):  # don't forget the class name
+    name = "simmate_clease"
+```
+
+!!! note
+    This file might seem silly, but it allows users to build complex apps that
+    include many other apps / subapps. Beginners will likely never look at this
+    file again.
+
+-------------------------------------------------------------------------------
+
+## Install our app
+
+1. Open the `pyproject.toml` file. This file is what tells Python how to install your code. It doesn't take much to install a package :smile:. As you project gets larger and needs other programs installed, you'll make note of them here. For now, nothing needs to be changed.
+
+2. While inside your new project folder, we want to "install" the project to
+your conda envirnment in "--editable" (-e) mode. This means you'll be make changes to your code and Python should automatically use your changes.
 ``` bash
+# replace "my_new_project" with the name of your project
 cd my_new_project
+pip install -e .
 ```
 
-3. Open up the `README.md` file in this folder and read through our directions. If you want a web-form of this guide, use [this link](https://github.com/jacksund/simmate/tree/main/src/simmate/configuration/example_project)
+3. Make sure this install worked by running these lines in python. You may need to restart your terminal/Spyder for this to work.
+
+=== "example 1"
+    ``` python
+    import example_app
+    from example_app.apps import ExampleAppConfig
+    ```
+
+=== "example 2"
+    ``` python
+    import simmate_clease
+    from simmate_clease.apps import SimmateCleaseConfig
+    ```
+
+You now have an installed app! But one issue remains: Simmate still doesn't know
+it exists yet. We need to tell Simmate to load it.
+
+-------------------------------------------------------------------------------
+
+## Register your app with Simmate
+
+
+1. Go to your simmate configuration folder. Recall from earlier tutorials that
+this where your database is stored, and it is located at...
+```
+# in your home directory
+~/simmate/
+```
+
+2. Look for the file `~/simmate/my_env-apps.yaml`, which is named after your
+conda environment. If you don't see one, then make a new one!
+
+3. In this file, add the following line:
+
+=== "example 1"
+    ``` yaml
+    example_app.apps.ExampleAppConfig
+    ```
+
+=== "example 2"
+    ``` yaml
+    simmate_clease.apps.SimmateCleaseConfig
+    ```
+
+4. Make sure Simmate can find and load your app
+
+=== "python"
+    ``` python
+    from simmate.configuration.django.settings import extra_apps
+    print(extra_apps)  # you should see your new app!
+    ```
+
+5. Make sure Simmate can configure your new app and it's tables properly
+=== "python"
+    ``` python
+    from simmate.database import connect
+    ```
+
+
+!!! tip
+    If you ever want to stop using this app, you can delete it from your `~/simmate/my_env-apps.yaml` file.
 
-4. After completing the steps in that readme, you've now registered your workflow and database tables to simmate!
+-------------------------------------------------------------------------------

docs/getting_started/custom_tables_and_apps/create_a_custom_table.md

@@ -1,20 +1,27 @@
-
 # Creating custom database tables
 
-Inside your project, there are example database tables that show how to build simple ones. It may seems super minimal, but there's really nothing else to do! 
+-------------------------------------------------------------------------------
+
+## Build custom tables
+
+Inside your project, there are example database tables that show how to build simple ones. It may seem super minimal, but there's really nothing else to do! 
 
-Recall from [the section on inheritance](https://jacksund.github.io/simmate/getting_started/access_the_database/intro_to_python_inheritance/) from tutorial 04. This is why building out new tables is so easy!
+Recall from [the section on inheritance](https://jacksund.github.io/simmate/getting_started/access_the_database/intro_to_python_inheritance/) from the "access the database" tutorial. This is why building out new tables is so easy. :fire:
 
 Some thing as simple as...
 
 ``` python
+# Don't run this code. Just read for understanding.
+
 from simmate.database.base_data_types import (
     table_column,
     Structure,
+    Calculation,  # useful for tables used in workflows
 )
 
-class MyCustomTable1(Structure):
-    new_column = table_column.FloatField(null=True, blank=True)
+class MyCustomTable1(Structure, Calculation):
+    pass  # nothing else is required unless you want to add custom columns/features
+
 ```
 
 ... will build out a new database table with all the following columns
@@ -35,25 +42,90 @@ class MyCustomTable1(Structure):
 - formula_full
 - formula_reduced
 - formula_anonymous
-- spacegroup (relation to Spacegroup)
-- new_column  # <--- note your new column here!
+- spacegroup (points to an entry in the Spacegroup table)
 ```
 
+However, we won't be able to import these tables or load data just yet. We will cover this next.
+
+!!! tip
+    Here we just show `Structure` data, but there are many more `base_data_types` that you can use. All types build out features for you automatically. Be sure to read through our guides in the [`simmate.database`](https://jacksund.github.io/simmate/full_guides/database/overview/) module for more info. Advanced database tables may require reading more on the [base data types](https://jacksund.github.io/simmate/full_guides/database/custom_tables/) too.
+
+-------------------------------------------------------------------------------
+
+## Add tables to your database
+
+1. Once we are happy with our tables in the `models.py` file, we can add them to
+our database by Simmate to update our database:
+``` bash
+simmate database update
+```
+
+2. Check the output of your `update` command. You should see that your new app
+was detected and that your tables were added.
+``` bash
+Migrations for 'example_app':
+  example_app/migrations/0001_initial.py
+    - Create model MyCustomTable2
+    - Create model MyCustomTable1
+```
+
+3. Make sure you can view the new tables in your database. Just remember
+that we need to connect to our database first. Note we are starting with `MyCustomTable2`
+here:
+
+``` python
+from simmate.database import connect
+
+from example_app.models import MyCustomTable2
+
+MyCustomTable2.objects.count()  # should output 0 bc we haven't added data yet
+```
+
+!!! info
+    In Django (which Simmate uses under the hood), a `DatabaseTable` is known as
+    a `Model`. So a model and table can be viewed as the same thing. Because we
+    are using Django, the file name `models.py` must stay this way. That's
+    where Django looks for your custom database tables.
+
+!!! tip
+    `simmate database reset` will also load your changes to the database. Just
+    make sure you say **no** to the prebuilt database.
+
+!!! danger
+    Whenever you change the `models.py` file, be sure to either (1) reset your database or (2) run `simmate database update` in order for your changes to be applied to your database.
+
+-------------------------------------------------------------------------------
+
+## Add data to your new table
+
 You can automatically fill this table using the `from_toolkit` method too:
 
 ``` python
+from simmate.database import connect
 from simmate.toolkit import Structure
 
+from example_app.models import MyCustomTable1
 
 nacl = Structure.from_file("NaCl.cif")
 
-new_entry = MyCustomTable1.from_toolkit(
-    structure=nacl, 
-    new_column=3.1415,
-)
+new_entry = MyCustomTable1.from_toolkit(structure=nacl)
 new_entry.save()
 ```
 
 !!! tip
-    There are many more `base_data_types` that you can use, and all types build out features for you automatically. Be sure to read through our guides in the [`simmate.database`](https://jacksund.github.io/simmate/full_guides/database/overview/) module for more info. Advanced database tables may require reading more on the [base data types](https://jacksund.github.io/simmate/full_guides/database/custom_tables/) too.
+    Manually filling your table with data is often not necessary. You can instead
+    attach your database to a workflow, which will fill it with data automatically.
+    We will learn how to do this in a later step.
+
+-------------------------------------------------------------------------------
+
+## Search your new data
+
+You can filter off results just like you would any other table. Be sure to go
+back through the earlier database tutorial if you need a refresher.
+
+``` python
+df = MyCustomTable1.objects.filter(nsites__lte=10).to_dataframe()
+```
 
+-------------------------------------------------------------------------------

docs/getting_started/custom_tables_and_apps/quick_start.md

@@ -4,35 +4,40 @@
 !!! warning
     There is no "quick tutorial" for this topic. Even advanced users should read everything!
 
-In this tutorial, you will learn how to build customized database table and also learn how to build out your customized features into "projects" (or "apps").
+In this tutorial, you will learn how to build customized database table and also learn how to build out your customized features into "projects".
 
+-------------------------------------------------------------------------------
 
-## Should I create a Simmate project?
+## Should you create a Simmate project?
 
-Whether you're a beginner or expert, building a big project or small one: the answer is 100% yes. :fire::fire::rocket:
+A custom Simmate project is required if you want to build a new database table or access your workflows in the website interface.
 
-At the end of the last tutorial, we posed a number of ideas. What if we wanted to...
+There are many more reasons you'd want to create a project. This includes wanting to...
 
-- use a custom database table to save our workflow results
-- access the workflow in the website interface
-- access our workflow from other scripts (and the `get_workflow` function)
-
-On top of these, we might also want to...
-
-- share workflows among a team
-- let others install your workflows after you publish a new paper
+- [x] use a custom database table to save our workflow results
+- [x] access the workflow in the website interface
+- [x] access our workflow from other scripts (and the `get_workflow` function)
+- [x] begin organizing our code into smaller files and easily import them
+- [x] share workflows among a team
+- [x] let others install your workflows after you publish a new paper
 
 All of these can be done using Simmate "projects". These projects are really just a folder of python files in a specific format (i.e. we have rules for naming files and what to put in them).
 
+-------------------------------------------------------------------------------
+
 ## Is this just creating a new package?
 
-For expert python users, you will notice that projects are indeed building a new python package. In fact, our `start-project` command is really just a cookie-cutter template! This can have huge implications for sharing research and code. With a fully-functional and published Simmate project (or "app"), you can upload your project for other labs to use via Github and PyPi! Then the entire Simmate community can install and use your custom workflows with Simmate. For them, it'd be as easy as doing
+Yep. For expert python users, you will notice that projects are indeed building a new python package. In fact, our `start-project` command acts just like a cookie-cutter template.
+
+This can have huge implications for sharing research and code. With a fully-functional and published Simmate project, you can upload your code for other labs to use via Github and PyPi! Then the entire Simmate community can install and use your custom workflows with Simmate. For them, it'd be as easy as doing
 
 1.  `pip install my_new_project`
-2.  adding `example_app.apps.ExampleAppConfig` to their `~/simmate/applications.yaml`
+2.  adding `example_app.apps.ExampleAppConfig` to their `~/simmate/my_env-apps.yaml`
 
 
 Alternatively, you can request that your app be merged into our Simmate repository, so that it is installed by default for all users. Whichever route you choose, your hard work should be much more accessible to the community and new users!
 
 !!! note 
     In the future, we hope to have a page that lists off apps available for download, but because Simmate is brand new, there currently aren't any existing apps outside of Simmate itself. Reach out to our team if you're interested in kickstarting a downloads page!
+
+-------------------------------------------------------------------------------