versioned docs

.github/workflows/cd.yml

@@ -5,6 +5,9 @@ on:
     branches:
     - develop
     - main
+  push:
+    branches:
+    - main
   release:
 
 jobs:
@@ -49,5 +52,4 @@ jobs:
       if: startsWith(github.ref, 'refs/tags')
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        python_version: ${{ matrix.python-version }}
-        pypi_token: ${{ secrets.PYPI_API_TOKEN }}
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
     - main
+    - develop
     # If your git repository has the Jupyter Book within some-subfolder next to
     # unrelated files, you can make this run only if a file within that specific
     # folder has been modified.
@@ -36,7 +37,9 @@ jobs:
 
     - name: build jupyter book
       working-directory: ${{runner.workspace}}/BuildingMOTIF/docs/
-      run: jupyter-book build .
+      run: |
+        jupyter-book config sphinx .
+        sphinx-build . _build/html -b html
 
     # TODO can we use an official GitHub Action? https://github.com/actions/deploy-pages
     - name: GitHub Pages action

.pre-commit-config.yaml

@@ -19,3 +19,4 @@ repos:
     -   id: mypy
         args: ["--install-types", "--non-interactive", "--ignore-missing-imports"]
         additional_dependencies: [sqlalchemy2-stubs <= 0.0.2a20, SQLAlchemy <= 1.4]
+exclude: docs/conf.py

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "jupyter-book config sphinx docs/"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

README.md

@@ -1,7 +1,7 @@
 # BuildingMOTIF
 
 [![codecov](https://codecov.io/gh/NREL/BuildingMOTIF/branch/main/graph/badge.svg?token=HAFSYH45NX)](https://codecov.io/gh/NREL/BuildingMOTIF) 
-[![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://nrel.github.io/BuildingMOTIF/)
+[![Documentation Status](https://readthedocs.org/projects/buildingmotif/badge/?version=latest)](https://buildingmotif.readthedocs.io/en/latest/?badge=latest)
 ![PyPI](https://img.shields.io/pypi/v/buildingmotif)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/buildingmotif)
 

buildingmotif/api/serializers/library.py

@@ -2,7 +2,7 @@
 
 from typing_extensions import TypedDict
 
-from buildingmotif.database.tables import DBLibrary
+from buildingmotif.database.tables import DBLibrary, DBTemplate
 
 LibraryDict = TypedDict(
     "LibraryDict",
@@ -43,9 +43,11 @@ def _serialize(library: DBLibrary) -> LibraryDict:
     :return: serialized library
     :rtype: LibraryDict
     """
+    templates: List[DBTemplate] = library.templates  # apleasing the type checker.
+
     return {
         "id": library.id,
         "name": library.name,
-        "template_ids": library.templates,
+        "template_ids": [t.id for t in templates],
         "shape_collection_id": library.shape_collection_id,
     }

docs/README.md

@@ -1,7 +1,7 @@
 # BuildingMOTIF
 
 [![codecov](https://codecov.io/gh/NREL/BuildingMOTIF/branch/main/graph/badge.svg?token=HAFSYH45NX)](https://codecov.io/gh/NREL/BuildingMOTIF) 
-[![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://nrel.github.io/BuildingMOTIF/)
+[![Documentation Status](https://readthedocs.org/projects/buildingmotif/badge/?version=latest)](https://buildingmotif.readthedocs.io/en/latest/?badge=latest)
 ![PyPI](https://img.shields.io/pypi/v/buildingmotif)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/buildingmotif)
 

docs/conf.py

@@ -0,0 +1,38 @@
+###############################################################################
+# Auto-generated by `jupyter-book config`
+# If you wish to continue using _config.yml, make edits to that file and
+# re-generate this one.
+###############################################################################
+add_module_names = False
+author = 'NREL'
+autodoc_default_options = {'members': True, 'member-order': 'bysource', 'undoc-members': True, 'private-members': False}
+autosummary_generate = True
+bibtex_bibfiles = ['bibliography.bib']
+comments_config = {'hypothesis': False, 'utterances': False}
+copyright = '2022'
+exclude_patterns = ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build']
+execution_allow_errors = False
+execution_excludepatterns = []
+execution_in_temp = False
+execution_timeout = 30
+extensions = ['sphinx_togglebutton', 'sphinx_copybutton', 'myst_nb', 'jupyter_book', 'sphinx_thebe', 'sphinx_comments', 'sphinx_external_toc', 'sphinx.ext.intersphinx', 'sphinx_design', 'sphinx_book_theme', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.viewcode', 'sphinxcontrib.bibtex', 'sphinx_jupyterbook_latex']
+external_toc_exclude_missing = False
+external_toc_path = '_toc.yml'
+html_baseurl = ''
+html_favicon = ''
+html_logo = ''
+html_sourcelink_suffix = ''
+html_theme = 'sphinx_book_theme'
+html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': 'docs', 'repository_url': 'https://github.com/NREL/BuildingMOTIF', 'repository_branch': 'main', 'google_analytics_id': '', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': True, 'announcement': '⚠️ This is an ALPHA release for testing purposes only ⚠️', 'use_repository_button': True, 'use_edit_page_button': False, 'use_issues_button': True}
+html_title = 'BuildingMOTIF Documentation'
+jupyter_cache = ''
+jupyter_execute_notebooks = 'force'
+latex_engine = 'pdflatex'
+myst_enable_extensions = ['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist']
+myst_url_schemes = ['mailto', 'http', 'https']
+nb_output_stderr = 'show'
+numfig = True
+pygments_style = 'sphinx'
+suppress_warnings = ['myst.domains']
+use_jupyterbook_latex = True
+use_multitoc_numbering = True

mypy.ini

@@ -1,2 +1,3 @@
 [mypy]
-plugins = sqlalchemy.ext.mypy.plugin
+plugins = sqlalchemy.ext.mypy.plugin
+exclude = docs/conf.py

pylama.ini

@@ -1,2 +1,3 @@
 [pylama]
 ignore = E203
+skip = docs/conf.py

tests/unit/api/test_library.py

@@ -27,6 +27,7 @@ def test_get_all_libraries(client, building_motif):
 def test_get_library(client, building_motif):
     # Setup
     lib = Library.create("my_library")
+    lib.create_template("my_template")
 
     # Act
     results = client.get(f"/libraries/{lib.id}")