Merge pull request #1 from gdsfactory/test_docs

add docs

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/test_doc_errors.py

@@ -0,0 +1,11 @@
+if __name__ == "__main__":
+    from gdsfactory.config import PATH
+
+    dirpath = PATH.repo / "docs" / "build" / "_html" / "reports"
+    error_files = list(dirpath.glob("*err.log"))
+
+    if error_files:
+        for error_file in error_files:
+            error = error_file.read_text()
+            print(error)
+        raise ValueError(f"{len(error_files)} errors in notebooks")

.github/workflows/pages.yml

@@ -0,0 +1,58 @@
+name: Sphinx docs to gh-pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    name: Sphinx docs to gh-pages
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - uses: actions/cache@v3
+        with:
+          path: |
+            ~/.gdsfactory/
+          key: 0.0.1
+          restore-keys: 0.0.1
+      - name: Installing the library
+        env:
+          TIDY3D_USER: ${{ secrets.TIDY3D_EMAIL }}
+          TIDY3D_PASS: ${{ secrets.TIDY3D_PASSWORD }}
+          SIMCLOUD_APIKEY: ${{ secrets.SIMCLOUD_APIKEY }}
+          DISPLAY: 1.0
+          DOCS: True
+          GDSFACTORY_DISPLAY_TYPE: klayout
+        shell: bash -l {0}
+        run: |
+          make dev
+          make docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: "./docs/_build/html/"
+
+  deploy-docs:
+    needs: build-docs
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/test_code.yml

@@ -0,0 +1,49 @@
+name: Test pre-commit, code and docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+      - uses: pre-commit/[email protected]
+  test_docs:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      max-parallel: 12
+      matrix:
+        python-version: [3.11]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - name: Install dependencies
+        run: |
+          make dev
+          pip freeze > requirements.txt
+      - uses: actions/upload-artifact@v3
+        with:
+          name: requirements
+          path: requirements.txt
+      - name: Test documentation
+        env:
+          TIDY3D_USER: ${{ secrets.TIDY3D_EMAIL }}
+          TIDY3D_PASS: ${{ secrets.TIDY3D_PASSWORD }}
+          DISPLAY: 1.0
+          DOCS: True
+          GDSFACTORY_DISPLAY_TYPE: klayout
+        run: |
+          mkdir -p $HOME/.tidy3d
+          make docs
+          python .github/test_doc_errors.py

.gitignore

@@ -6,13 +6,12 @@ __pycache__/
 # C extensions
 *.so
 
-
 # Sims
 *.fsp
 *.csv
 *.msh
 *.gds
-*.yml
+notebooks/*.yml
 *.stl
 *.oas
 

.pre-commit-config.yaml

@@ -14,123 +14,22 @@ repos:
         args: ["--pytest-test-first"]
       - id: trailing-whitespace
 
-  # - repo: https://github.com/hakancelik96/unimport
-  #   rev: 0.14.1
-  #   hooks:
-  #     - id: unimport
-  #       args: [--remove, --include-star-import]
-  # - repo: https://github.com/pycqa/isort
-  #   rev: "3a72e069635a865a92b8a0273aa829f630cbcd6f"
-  #   hooks:
-  #     - id: isort
-  #       files: "demo_project/.*"
-  #       args: ["--profile", "black", "--filter-files"]
-
   - repo: https://github.com/psf/black
     rev: "d9b8a6407e2f46304a8d36b18e4a73d8e0613519"
     hooks:
       - id: black
 
-
   - repo: https://github.com/kynan/nbstripout
     rev: e4c5b4dcbab4afa0b88b7a9243db42b1a8d95dde
     hooks:
       - id: nbstripout
         files: ".ipynb"
 
-  - repo: https://github.com/asottile/pyupgrade
-    rev: ddb39ad37166dbc938d853cc77606526a0b1622a
-    hooks:
-      - id: pyupgrade
-        args: [--py37-plus, --keep-runtime-typing]
-
-  # - repo: https://github.com/codespell-project/codespell
-  #   rev: 68ea3cff5eba266e0814794cce6cd19537f58137
-  #   hooks:
-  #     - id: codespell
-  #       args: ["-L TE,TE/TM,te,ba,FPR,fpr_spacing,ro,donot"]
-
   - repo: https://github.com/shellcheck-py/shellcheck-py
     rev: 953faa6870f6663ac0121ab4a800f1ce76bca31f
     hooks:
       - id: shellcheck
 
-  # - repo: https://github.com/pre-commit/pygrep-hooks
-  #   rev: 7b4409161486c6956bb3206ce96db5d56731b1b9 # Use the ref you want to point at
-  #   hooks:
-  #     - id: python-use-type-annotations
-
-  - repo: https://github.com/PyCQA/bandit
-    rev: fe1361fdcc274850d4099885a802f2c9f28aca08
-    hooks:
-      - id: bandit
-        args: [--exit-zero]
-        # ignore all tests, not just tests data
-        exclude: ^tests/
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.0.1"
-    hooks:
-      - id: mypy
-        exclude: ^(docs/|example-plugin/|tests/fixtures)
-        additional_dependencies:
-          - "pydantic"
-  # - repo: https://github.com/terrencepreilly/darglint
-  #   rev: master
-  #   hooks:
-  #     - id: darglint
-  # - repo: https://github.com/pycqa/pydocstyle
-  #   rev: "a6fe4222012e990042c86cdaaa904a8d059752ee"
-  #   hooks:
-  #     - id: pydocstyle
-  #       additional_dependencies: ["pydocstyle[toml]"]
-  # - repo: https://github.com/asottile/reorder_python_imports
-  #   rev: 2b2f0c74acdb3de316e23ceb7dd0d7945c354050
-  #   hooks:
-  #     - id: reorder-python-imports
-  # - repo: https://github.com/PyCQA/pylint
-  #   rev: v2.14.1
-  #   hooks:
-  #     - id: pylint
-  #       args: [--exit-zero]
-  # - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-  #   rev: 6565d773ca281682d7062d4c0be74538cc474cc9
-  #   hooks:
-  #     - id: pretty-format-java
-  #       args: [--autofix]
-  #     - id: pretty-format-kotlin
-  #       args: [--autofix]
-  #     - id: pretty-format-yaml
-  #       args: [--autofix, --indent, "2"]
-  # - repo: https://github.com/adrienverge/yamllint.git
-  #   rev: v1.21.0 # or higher tag
-  #   hooks:
-  #       - id: yamllint
-  #         args: [--format, parsable, --strict]
-  # - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
-  #   rev: 0.1.0 # or specific tag
-  #   hooks:
-  #       - id: yamlfmt
-  # - repo: https://github.com/pre-commit/pygrep-hooks
-  #   rev: "f6fb13e9516d1a9720a30a4049c930235abd642e"
-  #   hooks:
-  #     - id: python-check-blanket-noqa
-  #     - id: python-check-blanket-type-ignore
-  #     - id: python-no-log-warn
-  #     - id: python-no-eval
-  #     - id: python-use-type-annotations
-  #     - id: rst-backticks
-  #     - id: rst-directive-colons
-  #     - id: rst-inline-touching-normal
-  # - repo: https://github.com/nbQA-dev/nbQA
-  #   rev: 952c895a21aced4601165c43f77188559a5e825c
-  #   hooks:
-  #     - id: nbqa-black
-  #       additional_dependencies: [jupytext, black] # optional, only if you're using Jupytext
-  #     - id: nbqa-pyupgrade
-  #       args: ["--py37-plus"]
-      # - id: nbqa-flake8
-      # - id: nbqa-isort
-      #   args: ["--float-to-top"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     rev: "6a0ba1854991b693612486cc84a2254de82d071d"
     hooks:

Makefile

@@ -0,0 +1,15 @@
+install:
+	pip install -e .[dev,docs]
+	pip install pre-commit
+	pre-commit install
+
+dev: install
+
+update-pre:
+	pre-commit autoupdate
+
+git-rm-merged:
+	git branch -D `git branch --merged | grep -v \* | xargs`
+
+docs:
+	jb build docs

docs/_config.yml

@@ -0,0 +1,61 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: pictraining
+author: gdsfactory
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: cache
+  timeout: -1
+  allow_errors: true
+  # timeout: -1
+  # execute_notebooks: force
+  # execute_notebooks: "off"
+  # exclude_patterns:
+  #   - '*notebooks/devsim/01_pin_waveguide*'
+
+latex:
+  latex_engine: pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex: true # use sphinx-jupyterbook-latex for pdf builds as default
+
+# Add a bibtex file so that we can create citations
+
+html:
+  home_page_in_navbar: true
+  use_edit_page_button: true
+  use_repository_button: true
+  use_issues_button: true
+  baseurl: https://github.com/gdsfactory/gdsfactory-photonics-training
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/gdsfactory/gdsfactory-photonics-training
+  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)
+
+# launch_buttons:
+#   notebook_interface: jupyterlab
+#   colab_url: "https://colab.research.google.com"
+
+sphinx:
+  extra_extensions:
+    - "sphinx.ext.autodoc"
+    - "sphinx.ext.autodoc.typehints"
+    - "sphinx.ext.autosummary"
+    - "sphinx.ext.napoleon"
+    - "sphinx.ext.viewcode"
+    - "matplotlib.sphinxext.plot_directive"
+  config:
+    #autodoc_typehints: description
+    html_js_files:
+      - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
+    autodoc_type_aliases:
+      "ComponentSpec": "ComponentSpec"
+    nb_execution_show_tb: True
+    nb_execution_raise_on_error: true
+    nb_custom_formats:
+        .py:
+            - jupytext.reads
+            - fmt: py

docs/_toc.yml

@@ -0,0 +1,15 @@
+# Table of contents
+# Learn more at https://jterbook.org/customize/toc.html
+
+format: jb-book
+root: index
+chapters:
+  - file: layout
+    sections:
+        - file: notebooks/10_layout.ipynb
+        - file: notebooks/11_drc.ipynb
+        - file: notebooks/20_modesolver_fem.ipynb
+        - file: notebooks/21_modesolver_fdfd.ipynb
+        - file: notebooks/22_heater_fem.ipynb
+        - file: notebooks/30_mzi.ipynb
+        - file: notebooks/31_ring.ipynb

docs/index.md

@@ -0,0 +1,2 @@
+```{include} ../README.md
+```

docs/layout.md

@@ -0,0 +1,4 @@
+# Tutorial
+
+```{tableofcontents}
+```

docs/notebooks

@@ -0,0 +1 @@
+../notebooks