documentation overhaul

jdechalendar · Mar 3, 2024 · ab43c90 · ab43c90
1 parent dbb9b9c
commit ab43c90
Show file tree

Hide file tree

Showing 26 changed files with 341 additions and 23 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,66 @@
+.. _api:
+
+API reference
+=============
+This page gives an overview of all public ``gridemissions`` objects.
+
+.. currentmodule:: gridemissions
+
+Data structure
+--------------
+The main abstraction we use for holding data is :class:`GraphData`
+
+.. autosummary::
+  :toctree: generated/
+
+  GraphData
+  read_csv
+  GraphData.to_csv
+
+Accessing data
+
+.. autosummary::
+  :toctree: generated/
+
+  GraphData.get_data
+  GraphData.get_cols
+  GraphData.has_field
+
+There are several helper methods to check data consistency.
+
+.. autosummary::
+  :toctree: generated/
+
+  GraphData.check_all
+  GraphData.check_antisymmetric
+  GraphData.check_balance
+  GraphData.check_generation_by_source
+  GraphData.check_interchange
+  GraphData.check_nans
+  GraphData.check_positive
+
+Data cleaning
+-------------
+.. autosummary::
+  :toctree: generated/
+
+  BasicCleaner
+  BasicCleaner.process
+  RollingCleaner
+  RollingCleaner.process
+
+Data reconciliation
+-------------------
+.. autosummary::
+  :toctree: generated/
+
+   CvxCleaner
+   CvxCleaner.process
+
+Consumption-based emissions
+---------------------------
+.. autosummary::
+  :toctree: generated/
+
+  EmissionsCalc
+  EmissionsCalc.process
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,12 +16,10 @@
 from os.path import relpath, dirname
 import gridemissions
 
-sys.path.insert(0, os.path.abspath("../src/gridemissions"))
-
 
 # -- Project information -----------------------------------------------------
 
-project = "Grid emissions"
+project = "gridemissions"
 copyright = "2020, Jacques de Chalendar"
 author = "Jacques de Chalendar"
 
@@ -52,13 +50,13 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "pydata_sphinx_theme"
 
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 
 # based on numpy doc/source/conf.py

diff --git a/docs/config.rst b/docs/config.rst
@@ -0,0 +1,30 @@
+.. _config:
+
+Configuration
+=============
+Some configuration is needed for this project, to hold environment variables like data paths, API keys and passwords. The recommended option is to use a configuration file (``config.json``). A default is created for you the first time you import the package, in the folder ``~/.config/gridemissions``. ``~`` stands for your home directory. On Linux, this is what ``$HOME`` evaluates to, on Windows/OSX, this is the directory that contains your Documents, Desktop and Downloads folders.
+
+Alternatively, configuration settings can be read from environment variables, e.g. with
+
+.. code-block:: bash
+
+ export GRIDEMISSIONS_CONFIG_DIR_PATH="$HOME/.config/gridemissions_test"
+
+The config.json file
+--------------------
+Whenever you import the gridemissions module, the key-value pairs stored in ``config.json`` are loaded into a dictionary that then becomes available to you as the dictionary gridemissions.config. These can also be modified at runtime. At a minimum, your ``config.json`` should contain:
+
+* ``DATA_PATH``: path to local data store, by default ``~/data/gridemissions``
+* ``TMP_PATH``: for scratch data (e.g. when downloading data), by default ``~/tmp/gridemissions``
+
+Supported Environment Variables
+-------------------------------
+
+.. code-block:: bash
+
+ GRIDEMISSIONS_CONFIG_DIR_PATH       # the configuration directory (default: "$HOME/.config/gridemissions")
+ GRIDEMISSIONS_LOG_CONFIG_FILE_PATH  # the file used to store logging (default: "$HOME/.config/gridemissions/logging.conf")
+ GRIDEMISSIONS_CONFIG_FILE_PATH:     # the configuration file (default: "$HOME/.config/gridemissions/config.json")
+ GRIDEMISSIONS_DEFAULT_LOGGING_CONF  # the default logging configuration (default can be read within ./src/gridemissions/configure.py")
+ GRIDEMISSIONS_DATA_DIR_PATH         # the data directory (default: "$HOME/data/gridemissions")
+ GRIDEMISSIONS_TMP_DIR_PATH          # the temporary data directory (default: "$HOME/tmp/gridemissions")
diff --git a/docs/generated/gridemissions.BasicCleaner.process.rst b/docs/generated/gridemissions.BasicCleaner.process.rst
@@ -0,0 +1,6 @@
+gridemissions.BasicCleaner.process
+==================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: BasicCleaner.process
diff --git a/docs/generated/gridemissions.BasicCleaner.rst b/docs/generated/gridemissions.BasicCleaner.rst
@@ -0,0 +1,17 @@
+gridemissions.BasicCleaner
+==========================
+
+.. currentmodule:: gridemissions
+
+.. autoclass:: BasicCleaner
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~BasicCleaner.__init__
+      ~BasicCleaner.process
diff --git a/docs/generated/gridemissions.CvxCleaner.process.rst b/docs/generated/gridemissions.CvxCleaner.process.rst
@@ -0,0 +1,6 @@
+gridemissions.CvxCleaner.process
+================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: CvxCleaner.process
diff --git a/docs/generated/gridemissions.CvxCleaner.rst b/docs/generated/gridemissions.CvxCleaner.rst
@@ -0,0 +1,17 @@
+gridemissions.CvxCleaner
+========================
+
+.. currentmodule:: gridemissions
+
+.. autoclass:: CvxCleaner
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~CvxCleaner.__init__
+      ~CvxCleaner.process
diff --git a/docs/generated/gridemissions.EmissionsCalc.process.rst b/docs/generated/gridemissions.EmissionsCalc.process.rst
@@ -0,0 +1,6 @@
+gridemissions.EmissionsCalc.process
+===================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: EmissionsCalc.process
diff --git a/docs/generated/gridemissions.EmissionsCalc.rst b/docs/generated/gridemissions.EmissionsCalc.rst
@@ -0,0 +1,17 @@
+gridemissions.EmissionsCalc
+===========================
+
+.. currentmodule:: gridemissions
+
+.. autoclass:: EmissionsCalc
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~EmissionsCalc.__init__
+      ~EmissionsCalc.process
diff --git a/docs/generated/gridemissions.GraphData.check_all.rst b/docs/generated/gridemissions.GraphData.check_all.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_all
+==================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_all
diff --git a/docs/generated/gridemissions.GraphData.check_antisymmetric.rst b/docs/generated/gridemissions.GraphData.check_antisymmetric.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_antisymmetric
+============================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_antisymmetric
diff --git a/docs/generated/gridemissions.GraphData.check_balance.rst b/docs/generated/gridemissions.GraphData.check_balance.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_balance
+======================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_balance
diff --git a/docs/generated/gridemissions.GraphData.check_generation_by_source.rst b/docs/generated/gridemissions.GraphData.check_generation_by_source.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_generation\_by\_source
+=====================================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_generation_by_source
diff --git a/docs/generated/gridemissions.GraphData.check_interchange.rst b/docs/generated/gridemissions.GraphData.check_interchange.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_interchange
+==========================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_interchange
diff --git a/docs/generated/gridemissions.GraphData.check_nans.rst b/docs/generated/gridemissions.GraphData.check_nans.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_nans
+===================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_nans
diff --git a/docs/generated/gridemissions.GraphData.check_positive.rst b/docs/generated/gridemissions.GraphData.check_positive.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.check\_positive
+=======================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.check_positive
diff --git a/docs/generated/gridemissions.GraphData.get_cols.rst b/docs/generated/gridemissions.GraphData.get_cols.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.get\_cols
+=================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.get_cols
diff --git a/docs/generated/gridemissions.GraphData.get_data.rst b/docs/generated/gridemissions.GraphData.get_data.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.get\_data
+=================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.get_data
diff --git a/docs/generated/gridemissions.GraphData.has_field.rst b/docs/generated/gridemissions.GraphData.has_field.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.has\_field
+==================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.has_field
diff --git a/docs/generated/gridemissions.GraphData.rst b/docs/generated/gridemissions.GraphData.rst
@@ -0,0 +1,28 @@
+gridemissions.GraphData
+=======================
+
+.. currentmodule:: gridemissions
+
+.. autoclass:: GraphData
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~GraphData.__init__
+      ~GraphData.check_all
+      ~GraphData.check_antisymmetric
+      ~GraphData.check_balance
+      ~GraphData.check_generation_by_source
+      ~GraphData.check_interchange
+      ~GraphData.check_nans
+      ~GraphData.check_positive
+      ~GraphData.get_cols
+      ~GraphData.get_data
+      ~GraphData.has_field
+      ~GraphData.to_csv
+      ~GraphData.to_parquet
diff --git a/docs/generated/gridemissions.GraphData.to_csv.rst b/docs/generated/gridemissions.GraphData.to_csv.rst
@@ -0,0 +1,6 @@
+gridemissions.GraphData.to\_csv
+===============================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: GraphData.to_csv
diff --git a/docs/generated/gridemissions.RollingCleaner.process.rst b/docs/generated/gridemissions.RollingCleaner.process.rst
@@ -0,0 +1,6 @@
+gridemissions.RollingCleaner.process
+====================================
+
+.. currentmodule:: gridemissions
+
+.. automethod:: RollingCleaner.process
diff --git a/docs/generated/gridemissions.RollingCleaner.rst b/docs/generated/gridemissions.RollingCleaner.rst
@@ -0,0 +1,17 @@
+gridemissions.RollingCleaner
+============================
+
+.. currentmodule:: gridemissions
+
+.. autoclass:: RollingCleaner
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~RollingCleaner.__init__
+      ~RollingCleaner.process
diff --git a/docs/generated/gridemissions.read_csv.rst b/docs/generated/gridemissions.read_csv.rst
@@ -0,0 +1,6 @@
+gridemissions.read\_csv
+=======================
+
+.. currentmodule:: gridemissions
+
+.. autofunction:: read_csv
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,26 +1,20 @@
-.. Grid emissions documentation master file, created by
-   sphinx-quickstart on Sat Sep 19 15:20:32 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. gridemissions documentation master file
 
-Documentation for the gridemissions project
+Documentation for the gridemissions package
 ===========================================
 
+Introduction
+~~~~~~~~~~~~~
+The tools in this package power the visualization at `energy.stanford.edu/gridemissions`_, updated hourly. Associated datasets on electricity and emissions are made publicly available. In addition to tools to create the data, the gridemissions package provides a module to retrieve data from the API and methods to load and manipulate the data.
+
+Documentation contents
+~~~~~~~~~~~~~~~~~~~~~~
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-Configuration
-~~~~~~~~~~~~~
-To come.
 
-Workflows
-~~~~~~~~~~~~~
-To come
+   config
+   operations
+   api
 
-API reference
-~~~~~~~~~~~~~
-.. autosummary::
-   :toctree: generated/
 
-   api.retrieve
+.. _energy.stanford.edu/gridemissions: https://energy.stanford.edu/gridemissions