Documentation

.github/workflows/export_tutorials.yml

@@ -0,0 +1,72 @@
+name: "Export Tutorials"
+
+on:
+  push:
+    branches:
+      - "**"  # Run on push on all branches
+    paths:
+      - 'tutorials/**/*.ipynb'
+jobs:
+  export_tutorials:
+    permissions: write-all
+    runs-on: ubuntu-latest
+    env:
+      TUTORIAL_TIMEOUT: 1200s
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.8
+
+    - name: Install dependencies
+      run: |
+        # Dependencies for tutorials
+        python3 -m pip install --upgrade pip .[tutorial] black[jupyter]
+    - name: Setup FFmpeg
+      uses: FedericoCarboni/setup-ffmpeg@v2
+
+    - id: files
+      uses: jitterbit/get-changed-files@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        format: space-delimited
+
+    - name: Configure git
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+    - name: Export tutorials to .py and .html
+      run: |
+        set -x
+        for file in ${{ steps.files.outputs.all }}; do
+          if [[ $file == *.ipynb ]]; then
+            filename=$(basename $file)
+            pyfilename=$(echo ${filename%?????})py
+            timeout --signal=SIGKILL $TUTORIAL_TIMEOUT python -Xfrozen_modules=off -m jupyter nbconvert $file --to python --output $pyfilename --output-dir=$(dirname $file)
+            htmlfilename=$(echo ${filename%?????} | sed -e 's/-//g')html
+            htmldir="docs/source"/$(echo ${file%??????????????} | sed -e 's/-//g')
+            timeout --signal=SIGKILL $TUTORIAL_TIMEOUT python -Xfrozen_modules=off -m jupyter nbconvert --execute $file --to html --output $htmlfilename --output-dir=$htmldir
+          fi
+        done
+        set +x
+
+    - name: Run formatter
+      run: black tutorials/
+
+    - uses: benjlevesque/short-sha@v2.1
+      id: short-sha
+
+    - name: Remove unwanted files
+      run: |
+        rm -rf build/ tutorials/tutorial4/data/
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@v5.0.2
+      with:
+        labels: maintenance
+        title: Export tutorial changed in ${{ steps.short-sha.outputs.sha }}
+        branch: export-tutorial-${{ steps.short-sha.outputs.sha }}
+        base: ${{ github.head_ref }}
+        commit-message: export tutorials changed in ${{ steps.short-sha.outputs.sha }}
+        delete-branch: true

.github/workflows/sphinx-build.yml

@@ -14,7 +14,7 @@ jobs:
     - name: Create the new documentation
       uses: ammaraskar/sphinx-action@7.4.7
       with:
-        pre-build-command: "python3 -m pip install .[docs]"
+        pre-build-command: "python3 -m pip install .[doc]"
         docs-folder: "docs/"
 
     - name: Deploy

.github/workflows/testing_doc.yml

@@ -1,33 +1,23 @@
 name: Test Sphinx Documentation Build
 
 on:
-  push:
-    branches:
-      - "master"
-    paths:
-      - 'docs/**'
   pull_request:
     branches:
       - "master"
+      - "0.2"
     paths:
       - 'docs/**'
 
 jobs:
   docs:
     runs-on: ubuntu-latest
-
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
-    - name: Set up Python
-      uses: ammaraskar/sphinx-action@7.4.7
-      with:
-        pre-build-command: "python3 -m pip install .[docs]"
-        docs-folder: "docs/"
+    - name: Install Python dependencies
+      run: python3 -m pip install .[doc]
 
-    - name: Build Sphinx documentation
+    - name: Build Documentation
       run: |
-        cd docs
-        make html
-
+        make html SPHINXOPTS+='-W'
+      working-directory: docs/

docs/source/_cite.rst

@@ -1,7 +1,7 @@
 Cite PINA
 ==============
 
-If PINA has been significant in your research, and you would like to acknowledge the project in your academic publication,
+If **PINA** has been significant in your research, and you would like to acknowledge the project in your academic publication,
 we suggest citing the following paper:
 
 *Coscia, D., Ivagnes, A., Demo, N., & Rozza, G. (2023). Physics-Informed Neural networks for Advanced modeling. Journal of Open Source Software, 8(87), 5352.*

docs/source/_contributing.rst

@@ -0,0 +1,100 @@
+Contributing to PINA
+=====================
+
+First off, thanks for taking the time to contribute to **PINA**! 🎉 Your help makes the project better for everyone. This document outlines the process for contributing, reporting issues, suggesting features, and submitting pull requests.
+
+Table of Contents
+------------------------
+
+1. `How to Contribute`_
+2. `Reporting Bugs`_
+3. `Suggesting Enhancements`_
+4. `Pull Request Process`_
+5. `Code Style & Guidelines`_
+6. `Community Standards`_
+
+How to Contribute
+------------------------
+
+You can contribute in several ways:
+
+- Reporting bugs
+- Suggesting features/enhancements
+- Submitting fixes or improvements via Pull Requests (PRs)
+- Improving documentation
+
+We encourage all contributions, big or small!
+
+Reporting Bugs
+------------------------
+
+If you find a bug, please open an `issue <https://github.com/mathLab/PINA/issues>`_ and include:
+
+- A clear and descriptive title
+- Steps to reproduce the problem
+- What you expected to happen
+- What actually happened
+- Any relevant logs, screenshots, or error messages
+- Environment info (OS, Python version, dependencies, etc.)
+
+Suggesting Enhancements
+------------------------
+
+We welcome new ideas! If you have an idea to improve PINA:
+
+1. Check the `issue tracker <https://github.com/mathLab/PINA/issues>`_ or the `discussions <https://github.com/mathLab/PINA/discussions>`_ to see if someone has already suggested it.
+2. If not, open a new issue describing:
+   - The enhancement you'd like
+   - Why it would be useful
+   - Any ideas on how to implement it (optional but helpful)
+3. If you are not sure about (something of) the enhancement, we suggest opening a discussion to collaborate on it with the PINA community.
+
+Pull Request Process
+------------------------
+
+Before submitting a PR:
+
+1. Ensure there’s an open issue related to your contribution (or create one).
+2. `Fork <https://help.github.com/articles/fork-a-repo>`_ the repository and create a new branch from ``master``:
+
+   .. code-block:: bash
+
+      git checkout -b feature/my-feature
+
+3. Make your changes:
+   - Write clear, concise, and well-documented code
+   - Add or update tests where appropriate
+   - Update documentation if necessary
+4. Verify your changes by running tests:
+
+   .. code-block:: bash
+
+      pytest
+
+5. Properly format your code. If you want to save time, simply run:
+
+   .. code-block:: bash
+
+      bash code_formatter.sh
+
+7. Submit a `pull request <https://help.github.com/articles/creating-a-pull-request>`_ with a clear explanation of your changes and reference the related issue if applicable.
+
+Pull Request Checklist
+
+1. Code follows the project’s style guidelines
+2. Tests have been added or updated
+3. Documentation has been updated if necessary
+4. Pull request is linked to an open issue (if applicable)
+
+Code Style & Guidelines
+------------------------
+
+- Follow PEP8 for Python code.
+- Use descriptive commit messages (e.g. ``Fix parser crash on empty input``).
+- Write clear docstrings for public classes, methods, and functions.
+- Keep functions small and focused; do one thing and do it well.
+
+Community Standards
+------------------------
+
+By participating in this project, you agree to abide by our Code of Conduct. We are committed to maintaining a welcoming and inclusive community.