Merge pull request #293 from QMCSoftware/doc_req_updates

Doc req updates

.github/workflows/python-package-conda.yml

@@ -1,34 +1,36 @@
-name: QMCPy_CI
-
+name: QMCPy Automated Tests and Coverage Report
 on: [push]
 
 jobs:
-  test:
+  tests:
+    name: Tests on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
     strategy:
-      matrix:
-        platform: [ubuntu-latest, macos-latest, windows-latest]
-    runs-on: ${{ matrix.platform }}
+        matrix:
+            os: ["macos-latest", "ubuntu-latest", "windows-latest"]
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python
-      uses: actions/setup-python@v2
-      with:
-        python-version: 3.8
-    - name: Add conda to system path
-      run: |
-        # $CONDA is an environment variable pointing to the root of the miniconda directory
-        echo $CONDA/bin >> $GITHUB_PATH
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip setuptools wheel
-        pip install -r requirements/dev.txt
-        python -m pip install -e .
-    - name: Run Tests
-      run: |
-        make tests
-    - name: Upload to Codecov
-      run: |
-        python -m coverage xml -i # genereate coverage.xml
-        # python -m codecov -t e87cdb03-ccdd-44df-9849-8c5bc460cb9e  # fails without token
-        # bash <(curl https://codecov.io/bash)
-        curl -s https://codecov.io/bash | bash
+      - uses: actions/checkout@v2
+      - uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: qmcpy
+          environment-file: environment.yml
+          auto-activate-base: false
+      - shell: bash -l {0}
+        run: |
+          conda info
+          conda list
+      - name: Install QMCPy 
+        shell: bash -l {0}
+        run: |
+          pip install -e .
+      - name: Run Tests
+        shell: bash -l {0}
+        run: |
+          make tests
+      - name: Upload to Codecov
+        shell: bash -l {0}
+        run: |
+          python -m coverage xml -i # genereate coverage.xml
+          # python -m codecov -t e87cdb03-ccdd-44df-9849-8c5bc460cb9e  # fails without token
+          # bash <(curl https://codecov.io/bash)
+          curl -s https://codecov.io/bash | bash

CONTRIBUTING.md

@@ -1,122 +1,39 @@
 # For Contributors
 
-Thank you for you interest in contributing to the QMCPy package. The following sections describe how to get set up as a developer, some helpful commands, and a few suggestions before merging changes. Let us know if you have any trouble by sending an email to [qmc-software@googlegroups.com](mailto:qmc-software@googlegroups.com).
+Thank you for your interest in contributing to the QMCPy package!
 
-Here is an overview of the key steps:
+Please submit **pull requests** to the `develop` branch and **issues** using a template from `.github/ISSUE_TEMPLATE/`
 
-* [Dev Tools](https://qmcpy.org/references-for-python-and-mathematical-software-development/) has helpful links to development tools we often use, e.g., VSCode, git,  conda, and LaTeX. You should install Python, make sure Git is installed, and select an IDE (integrated development environment).
-* [This page](https://github.com/QMCSoftware/QMCSoftware/blob/master/CONTRIBUTING.md) has QMCPy-specific setup instructions, e.g., cloning the QMCSoftware Repo, setting up a conda virtual environment, generating documentation and running tests locally, etc. 
-  * Windows users would need to install [Cygwin](https://www.cygwin.com) or [MinGW](https://www.mingw-w64.org) to run UNIX commands such as `cd` and `make`.
-  * Others have run into an issue when running `pip install -e .` since not all machines ship with C/C++ compilers. If you run into this issue on Windows and are using VSCode, then compilers can be installed from [C/C++ for Visual Studio Code](https://code.visualstudio.com/docs/languages/cpp) to fix the problem.
-  * QMCPy uses Python 3.7 by default. If you are a Mac M1 user or wish to use another Python version for QMCPy development, consider [an experimental solution approach](https://github.com/QMCSoftware/QMCSoftware/tree/develop/requirements) and let us know if it works for you.
-* Once you get the `make tests` and `make doc_html` targets in QMCPy to run without errors, your setup should be working fine!
+If you develop a new component please consider writing a blog for [qmcpy.org](https://qmcpy.org)
 
----
+Join team communications by reaching out to us at [qmc-software@googlegroups.com](mailto:qmc-software@googlegroups.com)
 
-## Installation for Developers
 
-To enable `conda` environments, [install miniconda](https://docs.conda.io/en/latest/miniconda.html).
+## Installation 
 
-Then, setup the `qmcpy` virtual environment
+In a git enabled terminal (e.g. [bash](https://gitforwindows.org/) for Windows) with [conda](https://docs.conda.io/en/latest/miniconda.html) installed and C compilers enabled (Windows users may want to install [Cygwin](https://www.cygwin.com) or [MinGW](https://www.mingw-w64.org) and may find this [tutorial from Visual Studio Code](https://code.visualstudio.com/docs/languages/cpp) helpful), run
 
 ~~~
 git clone https://github.com/QMCSoftware/QMCSoftware.git
 cd QMCSoftware
 git checkout develop
-conda env create --name qmcpy python=3.7.12 --file requirements/environment.ymlv
+conda env create --file environment.yml
 conda activate qmcpy
 pip install -e .
 ~~~
 
-If setup with our `environment.yml` file fails, you can manually create the environment (minus a few extra dependencies)
-
-~~~
-git clone https://github.com/QMCSoftware/QMCSoftware.git
-cd QMCSoftware
-git checkout develop
-conda create -n qmcpy python=3.7.0
-conda activate qmcpy
-conda install conda-build
-conda develop .
-pip install -r requirements/dev.txt
-pip install -e .
-~~~
-
-To check for successful installation, run
+Doctests and unittests take a few minute to run with
 
 ~~~
 make tests
 ~~~
 
-Note that the C backend files can be explicitly recompiled with
-
-~~~
-pip install -e .
-~~~
-
-----
-
-## Documentation
-
-Automated project documentation is compiled with [Sphinx](http://www.sphinx-doc.org/). To compile HTML, PDF, or EPUB docs locally into `sphinx/_build/` you must install [pandoc](https://pandoc.org/installing.html), a [latex distribution](https://www.latex-project.org/get/), and add additional python requirements with the command
-
-~~~
-pip install -r requirements/dev_docs.txt
-~~~
-
-Then, use one of the following three commands the compile the documentation
-
-~~~
-make doc_html
-make doc_pdf
-make doc_epub
-~~~
-
-----
-
-## Workouts and Demos
-
-Workouts extensively test and compare the components of the QMCPy package. Demos, implemented as Jupyter notebooks, demonstrate functionality and uses cases for QMCPy. They often draw on results from corresponding workouts.
-
-To run all workouts (~10 min) use the command
-
-~~~
-make workout
-~~~
-
-----
-
-## Unit Tests
-
-Combined doctests and unittests, both fast (<1 sec) / long (<10 sec), can be run with
-
-~~~
-make tests
-~~~
-
-See the `makefile` for individual testing commands.
-
-----
-
-## Pull Requests
-
-Pull requests should be made into the `develop` branch, as we try and keep the `master` branch consistent with the current release.
-
-**For a QMCPy component (generator, algorithm, use case) try to ...**
-
-- incorporate and be consistent with other QMCPy components as much as possible.
-- keep naming conventions the same across similar components.
-- develop thorough documentation, including doctests. See `qmcpy/stopping_criterion/cub_qmc_sobol_g.py` as an example.
-- create fast and/or long unittests in the `test/` directory.
-- create a workout or demo showcasing your new component, preferably including
-    - a connection/comparison to available components.
-    - how the expected cost is realized.
-    - an overview of the relevant mathematics.
-    - figures to illustrate important features.
-    - references.
-- consider submitting a blog to put on the [QMCPy blogs site](http://qmcpy.wordpress.com/).
+After installing [Pandoc](https://pandoc.org/installing.html) and [$\LaTeX$](https://www.latex-project.org/get/), documentation may be compiled into your preferred format with
 
-**For a bug fix, try to**
+```
+doc_html
+doc_pdf
+doc_epub
+```
 
-- fix/add doctests and unittests.
-- update documentation/references.
+See the `makefile` for more commands and the [developers page](https://qmcpy.org/references-for-python-and-mathematical-software-development/) on [qmcpy.org](https://qmcpy.org) for more tools

environment.yml

@@ -0,0 +1,22 @@
+name: qmcpy
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - pip=22.1.2
+  - python=3.9.13
+  - sphinx=5.0.2
+  - pandoc>=2.2
+  - pip:
+    - numpy==1.23.0
+    - scipy==1.8.1
+    - pandas==1.4.3
+    - matplotlib==3.5.2
+    - jupyter==1.0.0
+    - coverage==6.4.1
+    - pytest==7.1.2
+    - pylint==2.14.4
+    - recommonmark==0.7.1
+    - sphinx-math-dollar==1.2.1
+    - sphinx-rtd-theme==1.0.0
+    - sphinx-markdown-tables==0.0.15

makefile

@@ -100,23 +100,12 @@ workout:
 	@python workouts/mc_vs_qmc/vary_dimension.py | tee workouts/mc_vs_qmc/out/vary_dimension.log
 
 exportcondaenv:
-	@-rm -f requirements/environment.yml 2>/dev/null &
-	@conda env export --no-builds | grep -v "^prefix: " > requirements/environment.yml
-
-exportpipreq:
-	@pip freeze > requirements/dev.txt
-
-conda_colab:
-	@conda create -n qmcpy python=3.7.0
-	@conda activate qmcpy
-	@conda install conda-build
-	@conda develop .
-	@pip install -r requirements/dev.txt
-	@pip install -e .
+	@-rm -f environment.yml 2>/dev/null &
+	@conda env export --no-builds | grep -v "^prefix: " > environment.yml
 
 conda_doc:
 	#   Assuming QMCPy repository is cloned locally and the correct branch is checked out
-	@conda env create --file requirements/environment.yml
+	@conda env create --file environment.yml
 	@conda activate qmcpy
 	@pip install -e .
 	#   Suggest to run `make tests` to check environment is working

readthedocs.yml

@@ -0,0 +1,6 @@
+version: 2
+
+formats: all
+
+conda:
+  environment: environment.yml