Fix docs build fail - lots of dependencies fixing (BayAreaMetro#51)

1. Adds test docs build on github actions
2. Combines dependencies for docs and general requirements
3. Pins jinja2 version <3.10 because of deprecation of something that MkDocs uses (and sphinx) - can be considered for removal later.

.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Publish docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - develop
+
+jobs:
+  mkdocs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          REQUIREMENTS: docs/requirements.txt
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish.yml

@@ -29,15 +29,4 @@ jobs:
         TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
       run: |
         python setup.py sdist bdist_wheel
-        twine upload dist/*
-    - name: Build Sphinx docs
-      run: |
-        cd docs
-        make html
-    - name: Deploy
-      if: success()
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        publish_branch: gh-pages
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: _build/html/
+        twine upload dist/*

.github/workflows/test.yml

@@ -33,3 +33,10 @@ jobs:
     - name: Test with pytest
       run: |
         pytest -s -m "not skipci"
+    - name: Test documentation build
+      uses: Tiryoh/actions-mkdocs@v0
+      with:
+        mkdocs_version: 'latest' 
+        requirements: 'docs/requirements.txt' 
+        configfile: 'mkdocs.yml' 
+

.gitignore

@@ -72,10 +72,8 @@ coverage.xml
 *.mo
 *.pot
 
-# Sphinx documentation
-docs/_build/
-docs/_generated/*
-docs/_autosummary/*
+# mkdocs documentation
+site/*
 
 # mkdocs documentation
 site/*

.markdownlint.yaml

@@ -0,0 +1,9 @@
+# includes/excludes all rules by default
+default: true
+
+# 4-space list indentation works best with MkDocs
+MD007:
+  indent: 4
+
+# Remove line length limit 
+MD013: false

README.md

@@ -13,9 +13,8 @@ If you are managing multiple python versions, we suggest using [`virtualenv`](ht
 The following instructions create and activate a conda environment (recommended) in which you can install:
 
 ```bash
-conda config --add channels conda-forge
-conda create python=3.7 -n <my_conda_environment>
-conda activate <my_conda_environment>
+conda env create -f environment.yml
+conda activate tm2py
 ```
 
 Basic installation instructions are as follows:
@@ -28,9 +27,8 @@ pip install tm2py
 If you want to install a more up-to-date or development version, you can do so by installing it from the `develop` branch as follows:
 
 ```bash
-conda config --add channels conda-forge
-conda create python=3.7  -n <my_conda_environment>
-conda activate <my_conda_environment>
+conda env create -f environment.yml
+conda activate tm2py
 pip install git+https://github.com/bayareametro/tm2py@develop
 ```
 
@@ -39,17 +37,36 @@ If you are going to be working on Lasso locally, you might want to clone it to y
 
 
 ```bash
-conda config --add channels conda-forge
-conda create python=3.7 -n <my_conda_environment>
-conda activate <my_lasso_environment>
+conda env create -f environment.yml
+conda activate tm2py
 git clone https://github.com/bayareametro/tm2py
 cd tm2py
 pip install -e .
 ```
 
+Note that you'll also need to install Emme's python packages into this conda environment.
+Following these instructions from an INRO community forum post: In the Emme Desktop application, open Tools->Application Options->Modeller, change your Python path as desired and click the "Install Modeller Package" button.
+
+If this is successful, the following packages will be visible in your environment when you type `pip list`:
+* inro-dynameq
+* inro-emme
+* inro-emme-agent
+* inro-emme-engine
+* inro-modeller
+
+Note that doing the emme package install will also install the package *pywin32*; if *pywin32* gets installed by other means (like
+conda or pip), then I got DLL load errors when tryring to import the emme packages, so I recommend uninstalling *pywin32* before
+installing the emme packages.
 
 ## Basic Usage
 
+Copy and unzip [example_union_test_highway.zip](https://mtcdrive.box.com/s/3entr016e9teq2wt46x1os3fjqylfoge) to a local
+drive and from within that directory run:
+
+```sh
+get_test_data <location>
+tm2py -s scenario.toml -m model.toml
+```
 
 ## Contributing
 

bin/get_test_data

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# Copies test data to examples directory or a given directory as an input argument
+# USAGE: get_test_data <optional: directory to put test data>
+
+TEST_DATA_LOCATION=https://mtcdrive.box.com/s/3entr016e9teq2wt46x1os3fjqylfoge
+TEST_DATA_NAME="UnionCity"
+DEFAULT_DIRECTORY="examples"
+
+echo "Retreiving $TEST_DATA_NAME data from $TEST_DATA_LOCATION"
+
+if [ "$#"==0 ]
+then
+    DIR=$(find . -name $DEFAULT_DIRECTORY)
+    echo "Finding directory:" $DIR
+    cd $DIR
+else
+    OUTDIR=$1
+    [ ! -d $OUTDIR ] && mkdir -p $OUTDIR
+    cd $OUTDIR
+    echo "Moved to provided directory:" $OUTDIR
+fi
+
+echo "Writing to $PWD"
+
+curl $TEST_DATA_LOCATION -L -o test_data.zip
+unzip test_data.zip -d $TEST_DATA_NAME
+rm test_data.zip /y

bin/get_test_data.bat

@@ -0,0 +1,20 @@
+REM Copies test data to examples directory or a given directory as an input argument
+REM USAGE: get_test_data.bat Optional <directory to put test data>
+REM ECHO OFF
+
+SET CWD=%cd%
+SET TEST_DATA_LOCATION=https://mtcdrive.box.com/s/3entr016e9teq2wt46x1os3fjqylfoge
+REM SET TEST_DATA_NAME=UnionCity
+SET DEFAULT_DIRECTORY=examples
+
+ECHO "Retreiving %TEST_DATA_NAME% data from %TEST_DATA_LOCATION%
+
+SET OUTDIR=%1
+if "%OUTDIR%"=="" SET OUTDIR=DEFAULT_DIRECTORY
+if not exist %OUTDIR% mkdir %OUTDIR%  
+CD %OUTDIR%
+ECHO "Writing to %CD%"
+
+curl -i -X GET %TEST_DATA_LOCATION% -L -o test_data.zip
+
+CD %CWD%

bin/tm2py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+
+import argparse
+
+from tm2py.controller import RunController
+
+def usage():
+    print("tm2py -s scenario.toml -m model.toml")
+
+def run():
+    parser = argparse.ArgumentParser(description="Main: run MTC TM2PY")
+
+    parser.add_argument(
+        "-s", "--scenario", required=True, help=r"Scenario config file path"
+    )
+    parser.add_argument("-m", "--model", required=True, help=r"Model config file path")
+
+    args = parser.parse_args()
+    controller = RunController([args.scenario, args.model])
+    controller.run()
+
+if __name__ == "__main__":
+    run()

bin/update_docs

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+import logging
+import os
+
+import tm2py
+
+# High-level settings
+MODULE_CLASS_DOC_LIST = [ 
+    ("classes_components.md",[("## Components", tm2py.components, 1)]),
+    ("classes_basic.md", [("## Basic", tm2py, 1)]),
+    ("classes_config.md", [("## Config", tm2py.config, 1)]),
+    ("classes_emme.md",[("## Emme", tm2py.emme, 3) ],
+    ),
+]
+
+# Basic setup
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+base_dir = os.path.dirname(os.path.dirname(__file__))
+docs_dir = os.path.join(base_dir,"docs")
+logger.info(f"Using docs directory:\n {docs_dir}")
+
+# Update class diagrams (currently using defaults)
+
+logger.info("Updating class diagrams")
+
+from tm2py.utils import doc_modules
+
+for _class_diagram_md,_module_list in MODULE_CLASS_DOC_LIST:
+    class_diagram_str = doc_modules.generate_md_class_diagram(_module_list)
+    class_diagram_outfile = os.path.join(docs_dir,"includes","class_diagrams",_class_diagram_md)
+    with open(class_diagram_outfile,'w') as f:
+        f.write(class_diagram_str)
+    logger.info(f"Updated class diagrams in:\n{class_diagram_outfile}")