Merge pull request #17 from catalyst-cooperative/dev

Sphinx docs build, RTD, unit tests

Author: zaneselvans

.gitignore

@@ -1,5 +1,6 @@
 # Catalyst specific files
 commit.txt
+*.swp
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.pre-commit-config.yaml

@@ -53,6 +53,13 @@ repos:
       - flake8-rst-docstrings
       - flake8-use-fstring
 
+# Check for errors in restructuredtext (.rst) files under the doc hierarchy
+- repo: https://github.com/PyCQA/doc8
+  rev: 0.11.1
+  hooks:
+  - id: doc8
+    args: [--config, tox.ini]
+
 - repo: https://github.com/myint/rstcheck
   rev: v5.0.0
   hooks:
@@ -70,6 +77,14 @@ repos:
       pass_filenames: false
       always_run: true
       entry: find notebooks \( -name \*.ipynb -not -name \*checkpoint.ipynb \) -type f -exec jupyter nbconvert --clear-output {} \;
+    - id: unit-tests
+      name: unit-tests
+      stages: [commit]
+      language: system
+      verbose: false
+      pass_filenames: false
+      always_run: true
+      entry: pytest --doctest-modules src/pudl_catalog tests/unit
 
 # Configuration for pre-commit.ci
 ci:
@@ -81,5 +96,5 @@ ci:
   autoupdate_branch: main
   autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
   autoupdate_schedule: weekly
-  skip: [nb-output-clear]
+  skip: [nb-output-clear, unit-tests]
   submodules: false

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+    configuration: docs/conf.py
+
+build:
+  image: testing
+  apt_packages:
+    - libsnappy-dev
+
+# Set the version of Python and requirements required to build your docs
+python:
+  version: "3.10"
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+          - docs

LICENSE LICENSE.txtLICENSE renamed to LICENSE.txt

@@ -3,27 +3,27 @@ The PUDL Data Catalog
 
 .. readme-intro
 
-.. image:: https://www.repostatus.org/badges/latest/concept.svg
-   :target: https://www.repostatus.org/#concept
-   :alt: Project Status: Concept - Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.
-
 .. image:: https://github.com/catalyst-cooperative/pudl-catalog/workflows/tox-pytest/badge.svg
    :target: https://github.com/catalyst-cooperative/pudl-catalog/actions?query=workflow%3Atox-pytest
    :alt: Tox-PyTest Status
 
-.. image:: https://img.shields.io/codecov/c/github/catalyst-cooperative/pudl-catalog
+.. image:: https://img.shields.io/codecov/c/github/catalyst-cooperative/pudl-catalog?style=flat&logo=codecov
    :target: https://codecov.io/gh/catalyst-cooperative/pudl-catalog
    :alt: Codecov Test Coverage
 
-.. image:: https://img.shields.io/pypi/v/catalystcoop.pudl_catalog
+.. image:: https://img.shields.io/readthedocs/catalystcoop-pudl-catalog?style=flat&logo=readthedocs
+   :target: https://catalystcoop-pudl-catalog.readthedocs.io/en/latest/
+   :alt: Read the Docs Build Status
+
+.. image:: https://img.shields.io/pypi/v/catalystcoop.pudl_catalog?style=flat&logo=python
    :target: https://pypi.org/project/catalystcoop.pudl_catalog/
    :alt: PyPI Latest Version
 
-.. image:: https://img.shields.io/conda/vn/conda-forge/catalystcoop.pudl_catalog
+.. image:: https://img.shields.io/conda/vn/conda-forge/catalystcoop.pudl_catalog?style=flat&logo=condaforge
    :target: https://anaconda.org/conda-forge/catalystcoop.pudl_catalog
    :alt: conda-forge Version
 
-.. image:: https://img.shields.io/pypi/pyversions/catalystcoop.pudl_catalog
+.. image:: https://img.shields.io/pypi/pyversions/catalystcoop.pudl_catalog?style=flat&logo=python
    :target: https://pypi.org/project/catalystcoop.pudl_catalog
    :alt: Supported Python Versions
 
@@ -121,7 +121,7 @@ this is weird).
    pudl_cat = intake.cat.pudl_cat
    list(pudl_cat)
 
-.. code:: txt
+.. code:: text
 
    ['hourly_emissions_epacems', 'hourly_emissions_epacems_partitioned']
 
@@ -135,7 +135,7 @@ but with all the Jinja template fields interpolated and filled in:
 
    pudl_cat.hourly_emissions_epacems
 
-.. code:: txt
+.. code:: text
 
    hourly_emissions_epacems:
      args:
@@ -172,7 +172,7 @@ types:
 
    pudl_cat.hourly_emissions_epacems.discover()
 
-.. code:: txt
+.. code:: text
 
    {'dtype': {'plant_id_eia': 'int32',
      'unitid': 'object',
@@ -243,15 +243,14 @@ on that dataframe to actually read the data and return a pandas dataframe:
        "co2_mass_tons",
    ]].head()
 
-====  ==============  ========  =========================  ======  =======  =============  =============  ======================  ===============  ====================  ===============
-  ..    plant_id_eia    unitid  operating_datetime_utc       year  state      facility_id    unit_id_epa    operating_time_hours    gross_load_mw    heat_content_mmbtu    co2_mass_tons
-====  ==============  ========  =========================  ======  =======  =============  =============  ======================  ===============  ====================  ===============
-   0             469         4  2019-01-01 07:00:00+00:00    2019  CO                  79            298                       1              203                2146.2            127.2
-   1             469         4  2019-01-01 08:00:00+00:00    2019  CO                  79            298                       1              203                2152.7            127.6
-   2             469         4  2019-01-01 09:00:00+00:00    2019  CO                  79            298                       1              204                2142.2            127
-   3             469         4  2019-01-01 10:00:00+00:00    2019  CO                  79            298                       1              204                2129.2            126.2
-   4             469         4  2019-01-01 11:00:00+00:00    2019  CO                  79            298                       1              204                2160.6            128.1
-====  ==============  ========  =========================  ======  =======  =============  =============  ======================  ===============  ====================  ===============
+.. csv-table::
+   :header: plant_id_eia, unitid, operating_datetime_utc, year, state, facility_id, unit_id_epa, operating_time_hours, gross_load_mw, heat_content_mmbtu, co2_mass_tons
+
+   469,4,2019-01-01 07:00:00+00:00,2019,CO,79,298,1.0,203.0,2146.2,127.2
+   469,4,2019-01-01 08:00:00+00:00,2019,CO,79,298,1.0,203.0,2152.7,127.6
+   469,4,2019-01-01 09:00:00+00:00,2019,CO,79,298,1.0,204.0,2142.2,127.0
+   469,4,2019-01-01 10:00:00+00:00,2019,CO,79,298,1.0,204.0,2129.2,126.2
+   469,4,2019-01-01 11:00:00+00:00,2019,CO,79,298,1.0,204.0,2160.6,128.1
 
 Benefits of Intake Catalogs
 ---------------------------

README.rst

@@ -0,0 +1,79 @@
+
+Catalyst Cooperative Code of Conduct
+====================================
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age,
+body size, disability, ethnicity, gender identity and expression, level of
+experience, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an
+appointed representative at an online or offline event. Representation of a
+project may be further defined and clarified by project maintainers.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at pudl@catalyst.coop. The project team
+will review and investigate all complaints, and will respond in a way that it
+deems appropriate to the circumstances. The project team is obligated to
+maintain confidentiality with regard to the reporter of an incident. Further
+details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the
+[Contributor Covenant version 1.4](http://contributor-covenant.org/version/1/4/)

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+===============================================================================
+The MIT License
+===============================================================================
+
+.. include:: ../LICENSE.txt

docs/LICENSE.rst

@@ -0,0 +1,3 @@
+.wy-table-responsive table td {
+    white-space: normal;
+}