Merge pull request #68 from materialsproject/jb_docs

update docs to jupyter book

.github/workflows/python-publish.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v4
       with:
         python-version: '3.x'
     - name: Install dependencies
@@ -41,7 +41,7 @@ jobs:
       - name: Install pandoc
         run: sudo apt-get install pandoc
 
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: '3.10'
           cache: pip
@@ -52,7 +52,7 @@ jobs:
           pip install -e .[strict]
           pip install -e .[docs]
       - name: Build
-        run: sphinx-build docs/source docs_build
+        run: jupyter-book build --path-output docs docs/source
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

.github/workflows/testing.yml

@@ -4,9 +4,8 @@ on:
   push:
     branches:
       - main
-
     tags:
-      - 'v*'
+      - "v*"
 
   pull_request:
     branches:
@@ -18,10 +17,9 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: "3.10"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -32,7 +30,6 @@ jobs:
           pip install -e .[dev]
           pre-commit install
 
-
       - name: Lint
         run: |
           pre-commit run --all-files --show-diff-on-failure
@@ -41,34 +38,34 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.8', '3.9', '3.10' ]
+        python-version: ["3.8", "3.9", "3.10"]
 
     env:
       PMG_MAPI_KEY: ${{ secrets.PMG_MAPI_KEY }}
 
     steps:
-    - uses: actions/checkout@v3
+      - uses: actions/checkout@v3
 
-    - uses: actions/setup-python@v3
-      with:
-        python-version:  ${{ matrix.python-version }}
-        cache: pip
-        cache-dependency-path: pyproject.toml
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
 
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e .[strict]
-        pip install -e .[tests]
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[strict]
+          pip install -e .[tests]
 
-    - name: Test
-      run: pytest --cov=pymatgen --cov-report=xml
+      - name: Test
+        run: pytest --cov=pymatgen --cov-report=xml
 
-    - uses: codecov/codecov-action@v1
-      if: matrix.python-version == 3.10
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-        file: ./coverage.xml
+      - uses: codecov/codecov-action@v1
+        if: matrix.python-version == 3.10
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
 
   docs:
     runs-on: ubuntu-latest
@@ -82,9 +79,9 @@ jobs:
       - name: Install pandoc
         run: sudo apt-get install pandoc
 
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: "3.10"
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -93,8 +90,4 @@ jobs:
           pip install -e .[strict]
           pip install -e .[docs]
       - name: Build
-        run: sphinx-build docs/source docs_build
-
-      - name: Test Jupyter Notebooks
-        run: |
-          pytest --nbmake --nbmake-kernel=python3 tutorials
+        run: jupyter-book build --path-output docs docs/source

.github/workflows/update-precommit.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
         with:
           python-version:  ${{ 3.10 }}
           cache: pip

.gitignore

@@ -139,3 +139,7 @@ examples/wip*
 .vscode/
 
 pymatgen/analysis/defects/corrections/kumagai_old.py
+
+docs.old/_build/
+
+docs.old/

docs/source/_config.yml

@@ -0,0 +1,43 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: pymatgen-analysis-defects
+author: Jimmy-Xuan Shen
+
+# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
+exclude_patterns            : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"]
+
+# Cache re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: cache
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/materialsproject/pymatgen-analysis-defects  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+  home_page_in_navbar: false
+  use_edit_page_button: true
+  baseurl: https://materialsproject.github.io/pymatgen-analysis-defects
+
+
+sphinx:
+  config:
+  extra_extensions:
+    - IPython.sphinxext.ipython_console_highlighting

docs/source/_toc.yml

@@ -0,0 +1,8 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: content/quickstart
+- file: content/defining-defects