From 04be8c27590236bacbfb90ff029ddc81842d38d9 Mon Sep 17 00:00:00 2001 From: Jeremy Pinto Date: Tue, 9 Aug 2022 14:21:50 -0400 Subject: [PATCH 1/5] remove mlflow from README (#64) * remove mlflow from README * add tensorboard information --- README.md | 10 +++++----- {{cookiecutter.project_slug}}/README.md | 16 +++++++++------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index daae06b..612fe93 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,13 @@ About A cookiecutter is a generic project template that will instantiate a new project with sane defaults. This repo contains our custom cookiecutter (`cookiecutter-pyml`) which will generate a new python deep learning package preconfigured with best practices in mind. It currently supports: -* Pytorch(PyTorch Lightning) -* Travis CI +* Pytorch (PyTorch Lightning) +* Github Actions (CI/CD) * Sphinx (documentation) -* MLFlow (experiment management) +* Tensorboard (experiment tracking) * Orion (hyperparameter optimization) -* Flake8 -* Pytest +* Flake8 (linting) +* Pytest (unit testing) More information on what a cookiecutter is [here.](https://cookiecutter.readthedocs.io) diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index a7d665b..be6895b 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{cookiecutter.project_slug}}/README.md @@ -100,11 +100,14 @@ For example, to run on your local machine without Orion: This will run a simple MLP on a simple toy task: sum 5 float numbers. You should see an almost perfect loss of 0 after a few epochs. -Note you have two new folders now: -* output: contains the models and a summary of the results. -* mlruns: produced by mlflow, contains all the data for visualization. -You can run mlflow from this folder (`examples/local`) by running -`mlflow ui`. +Note you have a new `output` folder which contains models and a summary of results: +* best_model: the best model checkpoint during training +* last_model: the last model checkpoint during training +* lightning_logs: contains the tensorboard logs. + +To view tensorboard logs, simply run: + + tensorboard --logdir output #### Run on a remote cluster (with Slurm) @@ -181,8 +184,7 @@ file (`config.yaml`) for your project (that contains the hyper-parameters). In general, you will want to run Orion in parallel over N slurm jobs. To do so, simply run `sh run.sh` N times. -When Orion has completed the trials, you will find the orion db file and the -mlruns folder (i.e., the folder containing the mlflow results). +When Orion has completed the trials, you will find the orion db file. You will also find the output of your experiments in `orion_working_dir`, which will contain a folder for every trial. From efdabe9a45a57115021b23c05260bd39ab67880f Mon Sep 17 00:00:00 2001 From: Jeremy Pinto Date: Wed, 10 Aug 2022 15:12:28 -0400 Subject: [PATCH 2/5] Change name of target branch from develop to development (#67) --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b92819..fd1626e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,11 +5,11 @@ on: push: branches: - master - - develop + - development pull_request: branches: - master - - develop + - development jobs: build: runs-on: ubuntu-latest From cf2815a0d032bfd864ad0c8d300957163e88b204 Mon Sep 17 00:00:00 2001 From: Jeremy Pinto Date: Thu, 11 Aug 2022 11:26:11 -0400 Subject: [PATCH 3/5] Update documentation (#66) * move docs requirements to a separate file * replace recommonmark with myst * Update instructions for docs * Update quickstart guides * Add requirements to the install process for doc testing * update sphinx for python3.10 * remove requirements, move extra dependencies to setup.py * Update dependency install in documentation test * Put all dependencies as project requirements * Update docs building info * Remove recommonmark, add myst Co-authored-by: Mirko Bronzi --- .../APPROVED_LIBRARIES.md | 5 +- {{cookiecutter.project_slug}}/README.md | 4 +- {{cookiecutter.project_slug}}/docs/conf.py | 6 +- .../docs/usage/guide.rst | 9 +++ .../docs/usage/quickstart.md | 60 +------------------ {{cookiecutter.project_slug}}/setup.py | 10 ++-- 6 files changed, 23 insertions(+), 71 deletions(-) diff --git a/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md b/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md index 028d33f..8a010ca 100644 --- a/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md +++ b/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md @@ -23,8 +23,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,7 +36,6 @@ 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/)) * 'torch', BSD-3 ([https://pypi.org/project/torch/](https://pypi.org/project/torch/)) @@ -52,4 +51,4 @@ we are not listing them all. Modifications since last approved version are in ** ## Pre-trained models * ADD IF USED -{%- endif %} \ No newline at end of file +{%- endif %} diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index be6895b..798f39e 100644 --- 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 index d7f63aa..6916349 100644 --- 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 index c13abd9..9e5b467 100644 --- 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 index 1b78411..cccecea 100644 --- 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 index 53b7ae5..a6793d4 100644 --- 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', From b08d3e001149e44b35679fadeb8c260ecd9dfa82 Mon Sep 17 00:00:00 2001 From: Mirko Bronzi Date: Mon, 15 Aug 2022 09:03:48 -0400 Subject: [PATCH 4/5] added instructions for approval (#68) * added instructions for approval * fixed typo --- .../APPROVED_LIBRARIES.md | 32 +++++++++++++------ 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md b/{{cookiecutter.project_slug}}/APPROVED_LIBRARIES.md index 8a010ca..0f325a6 100644 --- 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`) @@ -37,17 +59,9 @@ we are not listing them all. Modifications since last approved version are in ** * '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/)) * '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 From f1e27a61f84975eab9487ce38fa08d6aa056504e Mon Sep 17 00:00:00 2001 From: Mirko Bronzi Date: Mon, 15 Aug 2022 10:06:31 -0400 Subject: [PATCH 5/5] default to python3.9 (#69) --- .github/workflows/ci.yml | 4 ++-- cookiecutter.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fd1626e..ec21256 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,10 +15,10 @@ jobs: 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 index 32450cc..4ebf2a6 100644 --- 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",