Create documentation and deployment guidelines

[ejsimley]

Documentation will be written and hosted on the ENTR GitHub page explaining the components of the ENTR/OpenOA environment, data ingestion steps, how to deploy the software, and how to use the environment for wind plant operational assessment (including descriptions of the provided examples)

[ejsimley]

Quick start documentation using readthedocs/sphinx (https://github.com/entralliance/entr_docs):

• Installation process
• How to run example notebook
• How to import data
• Tag/release guidelines
• Process for adding to data tag list

[lewisarmistead]

Quick start documentation using readthedocs/sphinx (https://github.com/entralliance/entr_docs):

* Installation process

* How to run example notebook

* How to import data

* Tag/release guidelines

* Process for adding to data tag list

Building on this a bit further, here's what I'm envisioning for the sequence of getting started (steps to be documented):

• how to build and run the ENTR runtime with the appropriate mounts to local dirs for development
• how to run/materialize the ENTR warehouse models on the example data
• how to run example OpenOA notebook(s) on example warehouse data
• how to integrate data brought in by users into the warehouse
  • where to put data files (or how to bring in external db data)
  • steps for mapping new data to appropriate dimensions, building staging models, and integrating in generic ENTR fact tables
    • steps for creating new ENTR tags if none match data brought in by users and contribution guidelines for adding those to the ENTR-maintained tag list
• how to run example OpenOA notebook(s) on newly loaded data

In addition to those usage steps, guidance docs on the following:

• versioning (tags/release guidelines) for both runtime and warehouse
• production deployment patterns and guidelines
• contribution guidelines (related to tag addition point above and first iteration fo contribution guidelines #7)
• troubleshooting guidelines

[ejsimley]

@lewisarmistead that's a great list for the documentation sections! We could follow the example of OpenOA's documentation (https://openoa.readthedocs.io/en/latest/) and start with an overview of the project, then the first two steps you listed on building and running the ENTR runtime and warehouse. For the example OpenOA notebooks, we could link to the actual Jupyter notebooks, which already include documentation (as is done in the OpenOA documentation). In the sections on integrating new data, it would also be good to describe the process for performing preprocessing on the raw data prior to use in OpenOA. The versioning, production deployment patterns, and contribution guidelines could then all be part of a "Contributing" section at the end of the documentation.

[lewisarmistead]

@lewisarmistead that's a great list for the documentation sections! We could follow the example of OpenOA's documentation (https://openoa.readthedocs.io/en/latest/) and start with an overview of the project, then the first two steps you listed on building and running the ENTR runtime and warehouse. For the example OpenOA notebooks, we could link to the actual Jupyter notebooks, which already include documentation (as is done in the OpenOA documentation). In the sections on integrating new data, it would also be good to describe the process for performing preprocessing on the raw data prior to use in OpenOA. The versioning, production deployment patterns, and contribution guidelines could then all be part of a "Contributing" section at the end of the documentation.

@ejsimley, that all sounds good - let me know when you're able to create the bones of the docs, and I can start adding content in there!

[ejsimley]

Documentation structure:

• Introduction to ENTR environment, located in index.rst (Lewis, please review)
  • Few sentences about runtime and what it is used for (Lewis)
  • Few sentences about warehouse and what it is used for (Lewis)
  • Few sentences about OpenOA and what it is used for (Eric)
  • Few sentences about Docker container and what it is used for (Jordan)
• Installation and development guidelines, includes running Docker container, building runtime, warehouse, and container. Currently linking to entr_runtime dev branch readme (eventually link to main branch?). Review and update as needed (Lewis and Jordan).
• Running example OpenOA notebooks.
  • Using nbsphinx for documentation, this works locally for Eric but encountering errors related to pandoc when using Github Actions. Need to debug this issue (Jordan)
  • Intro paragraph explaining how to launch Jupiter server in Docker container and run example notebook (Jordan).
  • Then link to the AEP analysis notebook. (Eric)
  • Add additional documentation to AEP analysis notebook to describe ENTR relevant steps, like how to specify the wind plant name (Eric)
  • Finish documenting ENTR-relevant portions of PlantData class and link to this documentation (Jordan)
• Warehousing guidelines (How to load new data). For Q3 deliverable, just the csv method. We can add additional methods later. Includes where to save new csv files and how to update models. Eventually this can describe the process for adding pre-processing steps (Lewis).
• Production deployment guidelines (placeholder, complete after Q3 deliverable) (Lewis)
• Contribution guidelines (start a markdown file in docs repo for now)
  • Basic pull request process. Eventually need to explain steps for individual components like runtime and warehouse (Eric).
  • suggesting/adding a new data tag name (placeholder, complete after Q3 deliverable) (Lewis)
  • Versioning (tag/release) guidelines (placeholder, complete after Q3 deliverable) (Lewis)
• Troubleshooting guidelines (placeholder, complete after Q3 deliverable) (Lewis)