Add Jupyter Book

.github/workflows/jupyterbook.yml

@@ -0,0 +1,158 @@
+name: Build Jupyter Book
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+    - '*'
+  pull_request:
+    branches:
+      - master
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # environment:
+    #   name: github-pages
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/checkout@v4
+      with:
+        repository: tardis-sn/tardis-regression-data
+        path: tardis-regression-data
+        lfs: true
+        sparse-checkout: |
+          atom_data/kurucz_cd23_chianti_H_He.h5
+
+    - name: Setup environment
+      uses: ./.github/actions/setup_env
+      with:
+        os-label: linux-64
+
+    - run: |
+        micromamba install jupyter-book sphinx-autoapi
+        pip install -e . --user
+
+    - name: Copy atom_data
+      run: |
+        mkdir -p ~/Downloads/tardis-data && cp -a ./tardis-regression-data/atom_data/. ~/Downloads/tardis-data
+
+    - name: Build the book
+      run: |
+        jupyter-book build --all docs
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: "docs/_build/html"
+
+    - name: Set destination directory
+      run: |
+        BRANCH=$(echo ${GITHUB_REF#refs/heads/})
+        if [[ $EVENT == push ]] || [[ $EVENT == workflow_dispatch ]]; then
+
+          if [[ $BRANCH == $DEFAULT ]]; then
+            echo "DEST_DIR=" >> $GITHUB_ENV
+          else
+            echo "DEST_DIR=branch/$BRANCH" >> $GITHUB_ENV
+          fi
+
+        elif [[ $EVENT == pull_request_target ]]; then
+          echo "DEST_DIR=pull/$PR" >> $GITHUB_ENV
+
+        else
+          echo "Unexpected event trigger $EVENT"
+          exit 1
+
+        fi
+
+        cat $GITHUB_ENV
+      env:
+        DEFAULT: ${{ github.event.repository.default_branch }}
+        EVENT: ${{ github.event_name }}
+        PR: ${{ github.event.number }}
+
+    - name: Set clean branch option
+      run: |
+        if [[ $EVENT == workflow_dispatch ]]; then
+          echo "CLEAN_BRANCH=true" >> $GITHUB_ENV
+
+        else
+          echo "CLEAN_BRANCH=false" >> $GITHUB_ENV
+
+        fi
+
+        cat $GITHUB_ENV
+      env:
+        EVENT: ${{ github.event_name }}
+
+    - name: Deploy ${{ env.DEST_DIR }}
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.BOT_TOKEN }}
+        publish_branch: ${{ env.DEPLOY_BRANCH }}
+        publish_dir: ./docs/_build/html
+        destination_dir: ${{ env.DEST_DIR }}
+        keep_files: true
+        force_orphan: ${{ env.CLEAN_BRANCH }}
+        user_name: "TARDIS Bot"
+        user_email: "[email protected]"
+
+    - name: Find comment
+      uses: peter-evans/find-comment@v1
+      id: fc
+      with:
+        issue-number: ${{ github.event.number }}
+        body-includes: Hi, human.
+      if: always() && github.event_name == 'pull_request_target'
+
+    - name: Post comment (success)
+      uses: peter-evans/create-or-update-comment@v1
+      with:
+        token: ${{ secrets.BOT_TOKEN }}
+        issue-number: ${{ github.event.number }}
+        comment-id: ${{ steps.fc.outputs.comment-id }}
+        edit-mode: replace
+        body: |
+          *\*beep\* \*bop\**
+
+          Hi, human.
+
+          The **`${{ github.workflow }}`** workflow has **succeeded** :heavy_check_mark:
+
+          [**Click here**](${{ env.URL }}) to see your results.
+      env:
+        URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pull/${{ github.event.number }}/index.html
+      if: success() && github.event_name == 'pull_request_target'
+
+    - name: Post comment (failure)
+      uses: peter-evans/create-or-update-comment@v1
+      with:
+        token: ${{ secrets.BOT_TOKEN }}
+        issue-number: ${{ github.event.number }}
+        comment-id: ${{ steps.fc.outputs.comment-id }}
+        edit-mode: replace
+        body: |
+          *\*beep\* \*bop\**
+
+          Hi, human.
+
+          The **`${{ github.workflow }}`** workflow has **failed** :x:
+
+          [**Click here**](${{ env.URL }}) to see the build log.
+      env:
+        URL: https://github.com/${{ github.repository_owner }}/${{ github.event.repository.name }}/actions/runs/${{ github.run_id }}?check_suite_focus=true
+      if: failure() && github.event_name == 'pull_request_target'

docs/_config.yml

@@ -0,0 +1,47 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: TARDIS Documentation
+author: TARDIS RT Collaboration
+logo: graphics/tardis_banner.svg
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+  timeout: 1000
+
+# 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/executablebooks/jupyter-book  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: master  # 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
+
+
+sphinx:
+  extra_extensions:
+    - 'sphinx.ext.autodoc'
+    - 'sphinx.ext.autosummary'
+    - 'sphinx.ext.viewcode'
+    - 'autoapi.extension'
+  config:
+    html_extra_path: ['screenshots']
+    autodoc_member_order: 'bysource'
+    autosummary_generate: True
+    autoapi_dirs: ['../tardis']
+    autoapi_options: [ 'members', 'undoc-members', 'private-members', 'show-inheritance', 'show-module-summary', 'special-members',  ]

docs/_toc.yml

@@ -0,0 +1,38 @@
+format: jb-book
+root: index
+parts:
+  - caption: Getting Started
+    chapters:
+      - file: installation
+      - file: quickstart
+      - file: tutorials
+  - caption: Input/Output
+    chapters:
+      - file: io/hdf/index
+      - file: io/configuration/index
+      - file: io/model/index
+      - file: io/optional/index
+      - file: io/visualization/index
+      - file: io/output/index
+      - file: io/grid/TardisGridTutorial
+  - caption: Physics Walkthrough
+    chapters:
+      - file: physics/intro/index
+      - file: physics/setup/index
+      - file: physics/montecarlo/index
+      - file: physics/update_and_conv/update_and_conv
+      - file: physics/spectrum/index
+      - file: physics/tardisgamma/index
+  - caption: Contributing to TARDIS
+    chapters:
+      - file: contributing/CONTRIBUTING
+      - file: contributing/development/index
+      - file: contributing/tools/index
+      - file: contributing/CHANGELOG
+      - file: contributing/in_progress/index
+  - caption: Other Resources
+    chapters:
+      - file: resources/credits
+      - file: resources/research_done_using_TARDIS/research_papers
+      - file: resources/code_comparison/index
+      - file: resources/zreferences

docs/api.rst

@@ -0,0 +1,8 @@
+API documentation
+=================
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   tardis