Merge 80b3957 into 9b2daa8

.github/workflows/ci.yml

@@ -9,13 +9,13 @@ on:
     # Avoid using all the resources/limits available by checking only
     # relevant branches and tags. Other branches can be checked via PRs.
     branches: [main]
-    tags: ['v*']  # Push events to matching v*, i.e. v1.0, v20.15.10
-  pull_request:  # Run in every PR
-  workflow_dispatch:  # Allow manually triggering the workflow
+    tags: ["v*"] # Push events to matching v*, i.e. v1.0, v20.15.10
+  pull_request: # Run in every PR
+  workflow_dispatch: # Allow manually triggering the workflow
   schedule:
     # Run roughly every 15 days at 00:00 UTC
     # (useful to check if updates on dependencies break the package)
-    - cron: '0 0 1,16 * *'
+    - cron: "0 0 1,16 * *"
 
 concurrency:
   group: >-
@@ -30,9 +30,9 @@ jobs:
       wheel-distribution: ${{ steps.wheel-distribution.outputs.path }}
     steps:
       - uses: actions/checkout@v2
-        with: {fetch-depth: 0}  # deep clone for setuptools-scm
+        with: { fetch-depth: 0 } # deep clone for setuptools-scm
       - uses: actions/setup-python@v2
-        with: {python-version: "3.10"}
+        with: { python-version: "3.10" }
       - name: Lint code
         run: pipx run pre-commit run --all-files --show-diff-on-failure
       - name: Build package distribution files
@@ -54,12 +54,12 @@ jobs:
     strategy:
       matrix:
         python:
-        - 3.7  # oldest Python supported by PSF
-        - "3.10"  # newest Python that is stable
+          - 3.7 # oldest Python supported by PSF
+          - "3.10" # newest Python that is stable
         platform:
-        - ubuntu-latest
-#         - macos-latest
-#         - windows-latest
+          - ubuntu-latest
+    #         - macos-latest
+    #         - windows-latest
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v2
@@ -68,7 +68,7 @@ jobs:
           python-version: ${{ matrix.python }}
       - name: Retrieve pre-built distribution files
         uses: actions/download-artifact@v2
-        with: {name: python-distribution-files, path: dist/}
+        with: { name: python-distribution-files, path: dist/ }
       - name: Run tests
         run: >-
           pipx run tox
@@ -101,27 +101,27 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-        with: {python-version: "3.10"}
+        with: { python-version: "3.10" }
       - name: Retrieve pre-built distribution files
         uses: actions/download-artifact@v2
-        with: {name: python-distribution-files, path: dist/}
-#       - name: Build Changelog
-#         id: github_release
-#         uses: mikepenz/release-changelog-builder-action@v3
-#         env:
-#           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#       - name: Create Release
-#         uses: softprops/action-gh-release@v1
-#         with:
-#           tag_name: ${{ github.ref }}
-#           name: ${{ github.ref }}
-#           body: ${{steps.github_release.outputs.changelog}}
-#         env:
-#           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#       - name: "✏️ Generate release changelog" # updates CHANGELOG.md
-#         uses: heinrichreimer/github-changelog-generator-action@v2.3
-#         with:
-#           token: ${{ secrets.GITHUB_TOKEN }}
+        with: { name: python-distribution-files, path: dist/ }
+      #       - name: Build Changelog
+      #         id: github_release
+      #         uses: mikepenz/release-changelog-builder-action@v3
+      #         env:
+      #           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #       - name: Create Release
+      #         uses: softprops/action-gh-release@v1
+      #         with:
+      #           tag_name: ${{ github.ref }}
+      #           name: ${{ github.ref }}
+      #           body: ${{steps.github_release.outputs.changelog}}
+      #         env:
+      #           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #       - name: "✏️ Generate release changelog" # updates CHANGELOG.md
+      #         uses: heinrichreimer/github-changelog-generator-action@v2.3
+      #         with:
+      #           token: ${{ secrets.GITHUB_TOKEN }}
       - name: Publish Package
         env:
           # - https://pypi.org/help/#apitoken

README.md

@@ -40,18 +40,23 @@ class with and without optional relaxation via
 
 ```python
 # example_structures is a list of `pymatgen.core.structure.Structure` objects
-from xtal2png.core import XtalConverter
-from xtal2png.utils.data example_structures
+>>> from xtal2png import XtalConverter, example_structures
+>>>
+>>> xc = XtalConverter(relax_on_decode=False)
+>>> data = xc.xtal2png(example_structures, show=True, save=True)
+>>> decoded_structures = xc.png2xtal(data, save=False)
+>>> len(decoded_structures)
+2
+
+>> xc = XtalConverter(relax_on_decode=True)
+>> data = xc.xtal2png(example_structures, show=True, save=True)
+>> relaxed_decoded_structures = xc.png2xtal(data, save=False)
+>> len(relaxed_decoded_structures)
+2
 
-xc = XtalConverter(relax_on_decode=True)
-data = xc.xtal2png(example_structures, show=True, save=True)
-relaxed_decoded_structures = xc.png2xtal(data, save=False)
+```
 
 
-xc = XtalConverter(relax_on_decode=False)  # default behavior
-data = xc.xtal2png(example_structures, show=True, save=True)
-decoded_structures = xc.png2xtal(data, save=False)
-```
 
 ### Output
 

setup.cfg

@@ -96,11 +96,14 @@ console_scripts =
 addopts =
     --cov xtal2png --cov-report term-missing
     --verbose
+    --doctest-modules
+    --doctest-glob "README.md"
+    --doctest-continue-on-failure
 norecursedirs =
     dist
     build
     .tox
-testpaths = tests
+testpaths = tests README.md
 # Use pytest markers to select/deselect specific tests
 # markers =
 #     slow: mark tests as slow (deselect with '-m "not slow"')

tox.ini

@@ -64,6 +64,7 @@ deps =
     # ^  requirements.txt shared with Read The Docs
 commands =
     sphinx-build --color -b {env:BUILD} -d "{env:BUILDDIR}/doctrees" "{env:DOCSDIR}" "{env:BUILDDIR}/{env:BUILD}" {posargs}
+    doctest: python -m doctest README.md
 
 
 [testenv:publish]