add page for examples

.github/workflows/docs_pages_workflow.yml

@@ -0,0 +1,32 @@
+name: docs_pages_workflow
+
+# execute this workflow automatically when a we push to main
+on:
+  push:
+    branches: [ "dev" ]
+  pull_request:
+    branches: [ "main" ]
+jobs:
+
+  build_docs_job:
+    runs-on: ubuntu-latest
+    container: debian:buster-slim
+
+    steps:
+
+    - name: Prereqs
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        apt-get update
+        apt-get install -y git
+        git clone "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" .
+      shell: bash
+
+    - name: Execute script to build our documentation and update pages
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run:  |
+        chmod +x docs/docs_page.sh
+        "docs/docs_page.sh"
+      shell: bash

.gitignore

@@ -4,4 +4,8 @@ data_model/*
 !data_model/*.bin
 __pycache__
 
-.DS_Store
+.DS_Store
+
+_build/
+
+.vscode/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,137 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'PINN-FWI'
+copyright = '2023, Amir Mardan'
+author = 'Amir Mardan'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = extensions = [
+    'sphinx_rtd_theme',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
+
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+
+
+# -- Extension configuration -------------------------------------------------
+
+# add sourcecode to path
+import sys, os
+sys.path.insert(0, os.path.abspath('../'))
+
+############################
+# SETUP THE RTD LOWER-LEFT #
+############################
+try:
+   html_context
+except NameError:
+   html_context = dict()
+html_context['display_lower_left'] = True
+
+if 'REPO_NAME' in os.environ:
+	REPO_NAME = os.environ['REPO_NAME']
+else:
+	REPO_NAME = ''
+
+# SET CURRENT_LANGUAGE
+if 'current_language' in os.environ:
+   # get the current_language env var set by buildDocs.sh
+   current_language = os.environ['current_language']
+else:
+   # the user is probably doing `make html`
+   # set this build's current language to english
+   current_language = 'en'
+
+# tell the theme which language to we're currently building
+html_context['current_language'] = current_language
+
+# SET CURRENT_VERSION
+from git import Repo
+repo = Repo( search_parent_directories=True )
+
+if 'current_version' in os.environ:
+   # get the current_version env var set by buildDocs.sh
+   current_version = os.environ['current_version']
+else:
+   # the user is probably doing `make html`
+   # set this build's current version by looking at the branch
+   current_version = repo.active_branch.name
+
+# tell the theme which version we're currently on ('current_version' affects
+# the lower-left rtd menu and 'version' affects the logo-area version)
+html_context['current_version'] = current_version
+html_context['version'] = current_version
+
+# POPULATE LINKS TO OTHER LANGUAGES
+html_context['languages'] = [ ('en', '/' +REPO_NAME+ '/en/' +current_version+ '/') ]
+
+languages = ["en"] # [lang.name for lang in os.scandir('locales') if lang.is_dir()]
+for lang in languages:
+   html_context['languages'].append( (lang, '/' +REPO_NAME+ '/' +lang+ '/' +current_version+ '/') )
+
+# POPULATE LINKS TO OTHER VERSIONS
+html_context['versions'] = list()
+
+versions = [branch.name for branch in repo.branches]
+for version in versions:
+   html_context['versions'].append( (version, '/' +REPO_NAME+ '/'  +current_language+ '/' +version+ '/') )
+
+# POPULATE LINKS TO OTHER FORMATS/DOWNLOADS
+
+# settings for creating PDF with rinoh
+rinoh_documents = [(
+ master_doc,
+ 'target',
+ project+ ' Documentation',
+ '© ' +copyright,
+)]
+today_fmt = "%B %d, %Y"
+
+# settings for EPUB
+epub_basename = 'target'
+
+html_context['downloads'] = list()
+html_context['downloads'].append( ('pdf', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +project+ '-docs_' +current_language+ '_' +current_version+ '.pdf') )
+
+html_context['downloads'].append( ('epub', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +project+ '-docs_' +current_language+ '_' +current_version+ '.epub') )
+
+##########################
+# "EDIT ON GITHUB" LINKS #
+##########################
+
+html_context['display_github'] = True
+html_context['github_user'] = 'amirmardan'
+html_context['github_repo'] = 'piann_fwi'
+html_context['github_version'] = 'main/docs/'
+

docs/docs_page.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+set -x
+
+###################
+# INSTALL DEPENDS #
+###################
+
+apt-get update
+apt-get -y install git rsync python3-sphinx python3-sphinx-rtd-theme python3-stemmer python3-git python3-pip python3-virtualenv python3-setuptools
+
+python3 -m pip install --upgrade rinohtype pygments
+
+#####################
+# DECLARE VARIABLES #
+#####################
+
+# prevent git "detected dubious ownership" errors
+git config --global --add safe.directory "*"
+
+pwd
+ls -lah
+export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
+
+# make a new temp dir which will be our GitHub Pages docroot
+docroot=`mktemp -d`
+
+export REPO_NAME="${GITHUB_REPOSITORY##*/}"
+
+##############
+# BUILD DOCS #
+##############
+
+# first, cleanup any old builds' static assets
+make -C docs clean
+
+# get a list of branches, excluding 'HEAD' and 'gh-pages'
+versions="`git for-each-ref '--format=%(refname:lstrip=-1)' refs/remotes/origin/ | grep -viE '^(HEAD|gh-pages)$'`"
+for current_version in ${versions}; do
+
+   # make the current language available to conf.py
+   export current_version
+   git checkout ${current_version}
+
+   echo "INFO: Building sites for ${current_version}"
+
+   # skip this branch if it doesn't have our docs dir & sphinx config
+   if [ ! -e 'docs/conf.py' ]; then
+      echo -e "\tINFO: Couldn't find 'docs/conf.py' (skipped)"
+      continue
+   fi
+
+   languages="en `find docs/locales/ -mindepth 1 -maxdepth 1 -type d -exec basename '{}' \;`"
+   for current_language in ${languages}; do
+
+      # make the current language available to conf.py
+      export current_language
+
+      ##########
+      # BUILDS #
+      ##########
+      echo "INFO: Building for ${current_language}"
+
+      # HTML #
+      sphinx-build -b html docs/ docs/_build/html/${current_language}/${current_version} -D language="${current_language}"
+
+      # PDF #
+      sphinx-build -b rinoh docs/ docs/_build/rinoh -D language="${current_language}"
+      mkdir -p "${docroot}/${current_language}/${current_version}"
+      cp "docs/_build/rinoh/target.pdf" "${docroot}/${current_language}/${current_version}/${REPO_NAME}-docs_${current_language}_${current_version}.pdf"
+
+      # EPUB #
+      sphinx-build -b epub docs/ docs/_build/epub -D language="${current_language}"
+      mkdir -p "${docroot}/${current_language}/${current_version}"
+      cp "docs/_build/epub/target.epub" "${docroot}/${current_language}/${current_version}/${REPO_NAME}-docs_${current_language}_${current_version}.epub"
+
+      # copy the static assets produced by the above build into our docroot
+      rsync -av "docs/_build/html/" "${docroot}/"
+
+   done
+
+done
+
+# return to master branch
+git checkout master
+
+#######################
+# Update GitHub Pages #
+#######################
+
+git config --global user.name "${GITHUB_ACTOR}"
+git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+pushd "${docroot}"
+
+# don't bother maintaining history; just generate fresh
+git init
+git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+git checkout -b gh-pages
+
+# add .nojekyll to the root so that github won't 404 on content added to dirs
+# that start with an underscore (_), such as our "_content" dir..
+touch .nojekyll
+
+# add redirect from the docroot to our default docs language/version
+cat > index.html <<EOF
+<!DOCTYPE html>
+<html>
+   <head>
+      <title>${REPO_NAME} Docs</title>
+      <meta http-equiv = "refresh" content="0; url='/${REPO_NAME}/en/main'" />
+   </head>
+   <body>
+      <p>Please wait while you're redirected to our <a href="/${REPO_NAME}/en/main/">documentation</a>.</p>
+   </body>
+</html>
+EOF
+
+# Add README
+cat > README.md <<EOF
+# GitHub Pages Cache
+
+Nothing to see here. The contents of this branch are essentially a cache that's not intended to be viewed on github.com.
+
+
+If you're looking to update our documentation, check the relevant development branch's 'docs/' dir.
+
+EOF
+
+# copy the resulting html pages built from sphinx above to our new git repo
+git add .
+
+# commit all the new files
+msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}"
+git commit -am "${msg}"
+
+# overwrite the contents of the gh-pages branch on our github.com repo
+git push deploy gh-pages --force
+
+popd # return to main repo sandbox root
+
+# exit cleanly
+exit 0

docs/index.rst

@@ -0,0 +1,22 @@
+.. PINN-FWI documentation master file, created by
+   sphinx-quickstart on Thu Mar 28 00:06:12 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to PINN-FWI's documentation!
+====================================
+
+This is preliminary documentation for Physics-Informed Neural Networks for Full-Waveform Inversion (PINN-FWI)
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting started:
+
+   source/readme
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tools:
+
+   source/tools
+