Merge pull request #70 from mila-iqia/development

Release 2.3
mila-iqia · Aug 15, 2022 · 00c2251 · 00c2251
2 parents 354f2ad + f1e27a6
commit 00c2251
Show file tree

Hide file tree

Showing 8 changed files with 51 additions and 85 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -5,20 +5,20 @@ on:
   push:
     branches:
       - master
-      - develop
+      - development
   pull_request:
     branches:
       - master
-      - develop
+      - development
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - name: python-3.8
+    - name: python-3.9
       uses: actions/setup-python@v2
       with:
-        python-version: 3.8
+        python-version: 3.9
     - name: install-dependencies
       run: |
         python -m pip install --upgrade pip

diff --git a/cookiecutter.json b/cookiecutter.json
@@ -5,7 +5,7 @@
   "project_name": "Wonderful Project",
   "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}",
   "project_short_description": "{{ cookiecutter.project_name }} is wonderful!",
-  "python_version": "3.8",
+  "python_version": "3.9",
   "environment": ["mila", "generic"],
   "pypi_username": "{{ cookiecutter.github_username }}",
   "version": "0.0.1",

diff --git a/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md b/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md
@@ -1,4 +1,24 @@
 {%- if cookiecutter.environment == 'mila' %}
+__TODO_START__
+When starting a project, the other company needs to approve the libraries/tools that we use.
+There are two options that the company can choose:
+- Send a generic approval (via email) that all the libraries that we decide to use are pre-approved.
+- Keep a list of the libraries, and when a new library is added, add it to the list and ask the company to approve.
+
+If the former is selected, you can delete this file.
+If the latter, this file represents the list.
+
+The way it works is the following:
+- First, make sure that all the licenses listed below are still valid (i.e., they did not change). You can use the link to speedup this process.
+- Note that the last time the list was checked was on 2022-August-12.
+- Then, ask the company to approve the list by writing "approved" (or similar), with their git account (this will prove that the company approval is authentic).
+- When new libraries are added, create a new section below (`Dependencies as of ...`), where you copy the old list and you modify it according to your needs.
+- Ask the company to approve with the method above (git commit).
+
+Those instructions between TODO_START and TODO_END can be deleted.
+
+__TODO_END__
+
 Here is the list of dependencies required by Mila for the project development.
 Note that the following dependencies will trigger some other dependencies and for sake of simplicity,
 we are not listing them all. Modifications since last approved version are in **bold**.
@@ -15,6 +35,8 @@ we are not listing them all. Modifications since last approved version are in **
 * ZSH: MIT-like [zsh](http://zsh.sourceforge.net/)
 * OH-MY-ZSH: MIT [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/)
 * TMUX - ISC [tmux](https://github.com/tmux/tmux/)
+* [ipdb](https://pypi.org/project/ipdb/) BSD License (BSD), - A very useful debugger.
+* [ipython](https://pypi.org/project/ipython/) BSD, - A very useful interactive ipython shell
 
 ## Library dependencies
 (see `setup.py`)
@@ -23,8 +45,8 @@ we are not listing them all. Modifications since last approved version are in **
 * 'flake8-docstrings', MIT ([https://pypi.org/project/flake8-docstrings/](https://pypi.org/project/flake8-docstrings/))
 * 'gitpython', BSD ([https://pypi.org/project/GitPython/](https://pypi.org/project/GitPython/))
 * 'jupyter', BSD ([https://github.com/jupyter/jupyter/blob/master/LICENSE](https://github.com/jupyter/jupyter/blob/master/LICENSE))
-* 'jupyter notebook', BSD ([https://github.com/jupyter/notebook/blob/master/LICENSE](https://github.com/jupyter/notebook/blob/master/LICENSE))
 * 'jinja2', [3-clause BSD](https://jinja.palletsprojects.com/en/3.1.x/license/) ([https://palletsprojects.com/p/jinja/](https://palletsprojects.com/p/jinja/))
+* 'myst-parser, MIT, ([https://github.com/executablebooks/MyST-Parser](https://github.com/executablebooks/MyST-Parser))
 * 'orion', BSD [https://github.com/Epistimio/orion/blob/develop/LICENSE](https://github.com/Epistimio/orion/blob/develop/LICENSE)
 * 'pyyaml', MIT ([https://pypi.org/project/PyYAML/](https://pypi.org/project/PyYAML/))
 * 'pytest', MIT ([https://pypi.org/project/pytest/](https://pypi.org/project/pytest/))
@@ -36,20 +58,11 @@ we are not listing them all. Modifications since last approved version are in **
 * 'sphinx-rtd-theme', MIT ([https://pypi.org/project/sphinx-rtd-theme/](https://pypi.org/project/sphinx-rtd-theme/))
 * 'sphinxcontrib-napoleon', BSD ([https://pypi.org/project/sphinxcontrib-napoleon/](https://pypi.org/project/sphinxcontrib-napoleon/))
 * 'sphinxcontrib-katex', BSD (MIT) ([https://pypi.org/project/sphinxcontrib-katex/](https://pypi.org/project/sphinxcontrib-katex/))
-* 'recommonmark', MIT ([https://pypi.org/project/recommonmark/](https://pypi.org/project/recommonmark/))
 * 'tensorboard', Apache License 2.0 ([https://github.com/tensorflow/tensorboard](https://github.com/tensorflow/tensorboard))
-* 'tqdm', MIT ([https://pypi.org/project/tqdm/](https://pypi.org/project/tqdm/))
+* 'tqdm', MIT+Mozilla Public license ([https://pypi.org/project/tqdm/](https://pypi.org/project/tqdm/))
 * 'torch', BSD-3 ([https://pypi.org/project/torch/](https://pypi.org/project/torch/))
 
-## External dependencies to the project
-
-* [ipdb](https://pypi.org/project/ipdb/) BSD License (BSD), - A very useful debugger.
-* [ipython](https://pypi.org/project/ipython/) BSD, - A very useful interactive ipython shell
-* [jupytext](https://jupytext.readthedocs.io/en/latest/index.html)  MIT, - this library allows us to easily convert and sync .ipynb and .py files simultaneously - very useful for notebooks without needing a browser.
-* [pepermill](https://papermill.readthedocs.io/en/latest/) BSD, - very useful for running jupyter notebooks end-to-end directly from the CLI
-* [jupyter-vim-binding](https://github.com/lambdalisue/jupyter-vim-binding), MIT
-
 ## Pre-trained models
 
 * ADD IF USED 
-{%- endif %}
+{%- endif %}
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
@@ -201,8 +201,10 @@ You can check orion status with the following commands:
 
 ### Building docs:
 
-To automatically generate docs for your project, cd to the `docs` folder then run:
+Documentation is built using sphinx. It will automatically document all functions based on docstrings.
+To automatically generate docs for your project, navigate to the `docs` folder and build the documentation: 
 
+    cd docs
     make html
 
 To view the docs locally, open `docs/_build/html/index.html` in your browser.

diff --git a/{{cookiecutter.project_slug}}/docs/conf.py b/{{cookiecutter.project_slug}}/docs/conf.py
@@ -1,4 +1,3 @@
-from recommonmark.transform import AutoStructify
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -30,11 +29,11 @@
 extensions = []
 
 # enable use of markdown files
-extensions.append('recommonmark')
+extensions.append('myst_parser')
 
 # use the readthedocs theme
 extensions.append('sphinx_rtd_theme')
-extensions.append('sphinxcontrib.napoleon')
+extensions.append('sphinx.ext.napoleon')
 extensions.append('sphinxcontrib.katex')
 
 # autoapi extension for doc strings
@@ -57,7 +56,6 @@ def check_skip_member(app, what, name, obj, skip, options):
 def setup(app):
     """Handler to connect to the autoapi app."""
     app.connect("autoapi-skip-member", check_skip_member)
-    app.add_transform(AutoStructify)
 
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/{{cookiecutter.project_slug}}/docs/usage/guide.rst b/{{cookiecutter.project_slug}}/docs/usage/guide.rst
@@ -5,3 +5,12 @@ Quick Start
 -----------
 
 To get started, you have to first begin!
+
+Everybody loves Schrodinger's equation, why not put it everywhere?
+
+.. math::
+    i \hbar \frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat H \Psi(\mathbf{r},t)
+
+You can also add math or even link directly in your docstrings! For an example, click at the docstrings here:
+
+:py:meth:`{{cookiecutter.project_slug}}.models.optim.load_loss`
diff --git a/{{cookiecutter.project_slug}}/docs/usage/quickstart.md b/{{cookiecutter.project_slug}}/docs/usage/quickstart.md
@@ -1,62 +1,6 @@
-### How to start the project
+# Getting started
+## Quickstart
 
 Put your project instructions here, like
 
 `pip install -e .`
-
-
-### Add some math to your docs! 
-
-Everybody loves Schrodinger's equation, why not put it everywhere?
-```eval_rst
-:math:`i \hbar \frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat H \Psi(\mathbf{r},t)`
-```
-
-You can also add math directly in your docstrings! For an example, click at the docstrings here:
-```eval_rst
-:py:meth:`{{cookiecutter.project_slug}}.models.optim.load_loss`
-```
-
-You can even reference them directly anywhere for convenience, because clicking is for the lazy:
-```eval_rst
-.. autoclass:: {{cookiecutter.project_slug}}.models.optim.load_loss
-    :show-inheritance:
-    :noindex:
-```
-
-### More documentation magic
-
-A lot more information about what you can do with these docs is available [here](https://recommonmark.readthedocs.io/en/stable/auto_structify.html)
-
-For example:
-
-``` important:: We can have notes in markdown!
-```
-
-More craziness, wow, maybe rst is worth learning!
-
-
-``` sidebar:: Line numbers and highlights
-
-     emphasis-lines:
-       highlights the lines.
-     linenos:
-       shows the line numbers as well.
-     caption:
-       shown at the top of the code block.
-     name:
-       may be referenced with `:ref:` later.
-```
-
-``` code-block::
-     :linenos:
-     :emphasize-lines: 3,5
-     :caption: An example code-block with everything turned on.
-     :name: Full code-block example
-
-     # Comment line
-     import System
-     System.run_emphasis_line
-     # Long lines in code blocks create a auto horizontal scrollbar
-     System.exit!
-```
diff --git a/{{cookiecutter.project_slug}}/setup.py b/{{cookiecutter.project_slug}}/setup.py
@@ -12,17 +12,17 @@
         'gitpython==3.1.27',
         'jupyter==1.0.0',
         'jinja2<3.1.0',
+        'myst-parser==0.18.0',
         'orion>=0.2.4.post1',
         'pyyaml==6.0',
         'pytest==7.1.2',
         'pytest-cov==3.0.0',
         'pytorch_lightning==1.6.5',
-        'sphinx==3.5.4',
-        'sphinx-autoapi==1.8.1',
-        'sphinx-rtd-theme==0.5.2',
+        'sphinx==5.1.1',
+        'sphinx-autoapi==1.9.0',
+        'sphinx-rtd-theme==1.0.0',
         'sphinxcontrib-napoleon==0.7',
-        'sphinxcontrib-katex==0.7.2',
-        'recommonmark==0.7.1',
+        'sphinxcontrib-katex==0.8.6',
         'tensorboard==2.9.1',
         'tqdm==4.64.0',
         'torch==1.12.0',