upstream/master

Author: jonathanjdenney

.gitattributes

@@ -1,6 +1,5 @@
 # declare HTML, rST and test files as vendored/docs to exclude them when calculating repo languages on GitHub
-**/test_files/**/* linguist-vendored
+tests/files/**/* linguist-vendored
 cmd_line/* linguist-vendored
 docs/**/* linguist-generated
-docs_rst/**/* linguist-documentation
 dev_scripts/**/* linguist-vendored

.github/ISSUE_TEMPLATE/bug_report.md

@@ -5,7 +5,9 @@ about: Create a report to help us improve
 
 #### Description
 
-A clear and concise bug description.
+A clear and concise bug description. Please submit only issues regarding pymatgen only. If you encounter errors
+related to any of pymatgen's dependencies (e.g., [mp-api](https://github.com/materialsproject/api)), please post
+Issues on the respective Github Issues pages.
 
 #### Repro
 

.github/workflows/test.yml

@@ -5,8 +5,10 @@ name: Tests
 on:
   push:
     branches: [master]
+    paths-ignore: ["**/*.md", docs/**]
   pull_request:
     branches: [master]
+    paths-ignore: ["**/*.md", docs/**]
   release:
     types: [published]
   workflow_dispatch:
@@ -20,10 +22,14 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  pytest:
+  test:
     # prevent this action from running on forks
-    if: ${{ !github.event.pull_request.head.repo.fork }}
+    if: github.repository == 'materialsproject/pymatgen'
     strategy:
       fail-fast: false
       matrix:
@@ -60,8 +66,9 @@ jobs:
     env:
       PMG_MAPI_KEY: ${{ secrets.PMG_MAPI_KEY }}
       MPLBACKEND: Agg # https://github.com/orgs/community/discussions/26434
-      PMG_TEST_FILES_DIR: ${{ github.workspace }}/test_files
+      PMG_TEST_FILES_DIR: ${{ github.workspace }}/tests/files
       GULP_LIB: ${{ github.workspace }}/cmd_line/gulp/Libraries
+      PMG_VASP_PSP_DIR: ${{ github.workspace }}/tests/files
 
     steps:
       - uses: actions/checkout@v3
@@ -71,73 +78,103 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: pip
           cache-dependency-path: setup.py
-      - name: Add CLIs to GITHUB_PATH
-        if: runner.os != 'Windows'
+      - name: Copy CLIs to bin
+        if: runner.os == 'Linux'
         # This is the way to update env variables in a way that persist for the entire job.
         run: |
-          for pkg in cmd_line/*;
-            do echo "$(pwd)/cmd_line/$pkg/Linux_64bit" >> "$GITHUB_PATH";
-          done
+          sudo cp cmd_line/gulp/Linux_64bit/* /usr/local/bin/
+      - name: Install Bader
+        if: runner.os == 'Linux'
+        run: |
+          wget http://theory.cm.utexas.edu/henkelman/code/bader/download/bader_lnx_64.tar.gz
+          tar xvzf bader_lnx_64.tar.gz
+          sudo mv bader /usr/local/bin/
+        continue-on-error: true
+      - name: Install Enumlib
+        if: runner.os == 'Linux'
+        run: |
+          git clone --recursive https://github.com/msg-byu/enumlib.git
+          cd enumlib/symlib/src
+          export F90=gfortran
+          make
+          cd ../../src
+          make enum.x
+          sudo mv enum.x /usr/local/bin/
+          cd ..
+          sudo cp aux_src/makeStr.py /usr/local/bin/
+        continue-on-error: true
+      - name: Install Packmol
+        if: runner.os == 'Linux'
+        run: |
+          wget -O packmol.tar.gz https://github.com/m3g/packmol/archive/refs/tags/v20.14.2.tar.gz
+          tar xvzf packmol.tar.gz
+          export F90=gfortran
+          cd packmol-20.14.2
+          ./configure
+          make
+          sudo mv packmol /usr/local/bin/
+          cd ..
+          rm -rf .coverage*
+        continue-on-error: true
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip wheel
           python -m pip install numpy cython packaging
           python -m pip install -e '.[dev,optional]'
       - name: pytest split ${{ matrix.split }}
-        # to update the test durations, run
-        # pytest --store-durations --durations-path test_files/.pytest-split-durations
-        # and commit the results (requires pip install pytest-split)
         run: |
-          pytest --cov=pymatgen --splits 10 --group ${{ matrix.split }} --durations-path test_files/.pytest-split-durations
+          pytest --cov=pymatgen --splits 10 --group ${{ matrix.split }} --durations-path tests/files/.pytest-split-durations tests
       - name: Upload coverage
+        # Only upload coverage for ubuntu py3.11 runs. Continue on error as coverage is not critical.
+        if: github.event_name != 'pull_request' && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
         uses: actions/upload-artifact@v3
         with:
           name: coverage-${{ matrix.split }}
           path: .coverage
 
   coverage:
-    needs: pytest
+    # Only upload coverage for ubuntu py3.11 runs. Continue on error as coverage is not critical.
+    if: github.event_name != 'pull_request'
+    needs: test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.10"
-      - name: Install Coverage
-        run: python -m pip install coverage
       - name: Download coverage artifacts
-        continue-on-error: true
         uses: actions/download-artifact@v3
-      - name: Run coverage
-        continue-on-error: true
+      - name: Combine coverage
         run: |
-          coverage combine coverage*/.coverage*
-          coverage report
-          coverage xml
-      - name: Coveralls Python
-        continue-on-error: true
-        uses: AndreMiras/coveralls-python-action@v20201129
+          pip install coverage[toml]
+          find . -name "*.pyc" -delete
+          for i in {1..10}; do mv coverage-$i/.coverage .coverage.$i; rm -rf coverage-$i; done
+          coverage combine
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true
 
   build_sdist:
-    needs: pytest
-    name: Build source distribution
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.task == 'release')
+    needs: test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         name: Install Python
         with:
           python-version: "3.10"
-      - run: python -m pip install build
+      - run: |
+          python -m pip install build
+          pip install -e .
       - name: Build sdist
         run: python -m build --sdist
       - uses: actions/upload-artifact@v3
         with:
           path: dist/*.tar.gz
 
   build_wheels:
-    needs: pytest
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.task == 'release')
+    needs: test
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
@@ -146,7 +183,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.12.3
+        uses: pypa/cibuildwheel@v2.14.1
         env:
           CIBW_BUILD: cp${{ matrix.python-version }}-*
       - name: Save artifact

.gitignore

@@ -14,6 +14,7 @@ dependencies/spglib*/build
 pymatgen/pymatgen.cfg
 dist
 _build
+_site
 build
 .project
 .pydevproject

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-exclude: ^(docs|.*test_files|cmd_line|tasks.py)
+exclude: ^(docs|tests/files|cmd_line|tasks.py)
 
 ci:
   autoupdate_schedule: monthly
@@ -8,7 +8,7 @@ ci:
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.275
+    rev: v0.0.285
     hooks:
       - id: ruff
         args: [--fix]
@@ -17,22 +17,21 @@ repos:
     rev: v4.4.0
     hooks:
       - id: check-yaml
-        exclude: pymatgen/analysis/vesta_cutoffs.yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.7.0
     hooks:
       - id: black
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.4.0
+    rev: v1.5.1
     hooks:
       - id: mypy
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.4
+    rev: v2.2.5
     hooks:
       - id: codespell
         stages: [commit, commit-msg]
@@ -45,3 +44,18 @@ repos:
       - id: cython-lint
         args: [--no-pycodestyle]
       - id: double-quote-cython-strings
+
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.16.0
+    hooks:
+      - id: blacken-docs
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.35.0
+    hooks:
+      - id: markdownlint
+        # MD013: line too long
+        # MD033: no inline HTML
+        # MD041: first line in a file should be a top-level heading
+        # MD025: single title
+        args: [--disable, MD013, MD025, MD033, MD041, "--"]

ADMIN.md

@@ -9,10 +9,11 @@ The general procedure for releasing `pymatgen` comprises the following
 steps:
 
 1. Make sure all CI checks are green. We don't want to release known bugs.
-2. Update and edit changelog.
-3. Release PyPI versions + doc.
-4. Release `conda` versions.
-5. Release Dash documentation.
+1. Update changelog.
+1. Run `invoke make-doc` to update the HTML docs.
+1. Tag the latest commit with `git tag v<yyyy.mm.dd>`.
+1. Make a GitHub release with auto-generated release notes.
+1. Make sure the release action runs that publishes the new version to PyPI and conda-forge runs to completion.
 
 ## Initial setup
 
@@ -23,72 +24,29 @@ You will also need `sphinx` and `doc2dash`.
 pip install --upgrade invoke sphinx doc2dash
 ```
 
-Add your PyPI username and password and GITHUB_RELEASE_TOKEN into your
-environment:
-
-```sh
-export TWINE_USERNAME=PYPIUSERNAME
-export TWINE_PASSWORD=PYPIPASSWORD
-export GITHUB_RELEASES_TOKEN=TOKEN_YOU_GET_FROM_GITHUB
-```
-
-You may want to add these to your .bash_profile to avoid having to type
-these each time.
-
-### Machine-specific issues
-
-The above instructions are general, but some known issues are machine-specific:
-
-- Installing lxml via pip required <span
-  class="title-ref">STATIC_DEPS=true pip install lxml</span> on macOS
-  10.13.
-- It can be useful to <span class="title-ref">pip install --upgrade pip
-  twine setuptools</span> (this may be necessary if there are
-  authentication errors when connecting to PyPI).
-- You may have to <span class="title-ref">brew install hdf5
-  netcdf</span> or similar to be able to pip install the optional
-  requirement <span class="title-ref">netCDF4</span>.
-
 ## Doing the release
 
-Ensure appropriate environment variables are set including <span
-class="title-ref">DISCOURSE_API_USERNAME</span>, <span
-class="title-ref">DISCOURSE_API_KEY</span> and <span
-class="title-ref">GITHUB_RELEASES_TOKEN</span>.
-
-First update the change log. The autogenerated change log is simply a
-list of commit messages since the last version. Make sure to edit the
-log for brevity and to attribute significant features to appropriate
-developers:
+First update the change log. The autogenerated change log is simply a list of commit messages since the last version. Make sure to edit the log for brevity and to attribute significant features to appropriate developers:
 
 ```sh
 invoke update-changelog
 ```
 
-Then, do the release with the following sequence of commands (you can
-put them in a bash script in your PATH somewhere):
+Then, do the release with the following sequence of commands (you can put them in a bash script in your PATH somewhere):
 
 ```sh
 invoke release --notest --nodoc
 invoke update-doc
 python setup.py develop
 ```
 
-Double check that the releases are properly done on Pypi. If you are
-releasing on a Mac, you should see a pymatgen.version.tar.gz and two
-wheels (Py37 and P). There will be a py37 wheel for Windows that is
-generated by Appveyor.
+Double check that the releases are properly done on Pypi. If you are releasing on a Mac, you should see a pymatgen.version.tar.gz and two wheels (Py37 and P). There will be a py37 wheel for Windows that is generated by Appveyor.
 
 ## Materials.sh
 
-Fork and clone the
-[materials.sh](https://github.com/materialsvirtuallab/materials.sh).
-This repo contains the `conda` skeletons to build the `conda` versions for
-various matsci codes on the Anaconda [matsci
-channel](https://anaconda.org/matsci).
+Fork and clone the [materials.sh](https://github.com/materialsvirtuallab/materials.sh). This repo contains the `conda` skeletons to build the `conda` versions for various matsci codes on the Anaconda [matsci channel](https://anaconda.org/matsci).
 
-The first time this is run, you may need to <span class="title-ref">pip
-install beautifulsoup4</span>.
+The first time this is run, you may need to `pip install beautifulsoup4`.
 
 If you doing this for the first time, make sure conda-build and
 anaconda-client are installed:
@@ -114,16 +72,3 @@ versions.
 
 Check that the [matsci channel](https://anaconda.org/matsci) versions
 are properly updated.
-
-## Dash docs
-
-Fork and clone the [Dash User Contributions
-repo](https://github.com/Kapeli/Dash-User-Contributions).
-
-Generate the offline Dash doc using:
-
-```sh
-invoke contribute-dash
-```
-
-Create a pull request and submit.