Add quick start and tutorials to documentation

.github/workflows/build-and-test.yml

@@ -10,6 +10,10 @@ on:
   schedule:
     - cron: "0 0 * * *"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-and-test:
     runs-on: ${{ matrix.os }}

.github/workflows/build-docs.yml

@@ -1,15 +1,25 @@
 name: Build Documentation
 
 on:
+  workflow_dispatch:
   push:
     branches:
-      - "*"
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
 
   schedule:
     - cron: "0 0 * * *"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  build-and-test:
+  build-and-deploy:
     runs-on: "ubuntu-latest"
     env:
       PYVISTA_OFF_SCREEN: "True"
@@ -35,3 +45,32 @@ jobs:
 
       - name: Build docs
         run: make -C docs html
+
+      - name: Upload HTML documentation
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build
+          path: docs/_build/html/
+
+      # Deploy to microgen-docs/main only for main/master branch
+      - name: Deploy HTML documentation (main branch)
+        if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          personal_token: ${{ secrets.MICROGEN_DOC_TOKEN }}
+          external_repository: 3MAH/microgen-docs
+          publish_branch: main
+          publish_dir: ./docs/_build/html
+          force_orphan: true
+
+      # Deploy to microgen-docs/PRXX for each pull request
+      - name: Deploy HTML documentation (pull request)
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          personal_token: ${{ secrets.MICROGEN_DOC_TOKEN }}
+          external_repository: 3MAH/microgen-docs
+          publish_branch: PR${{ github.event.pull_request.number }}
+          publish_dir: ./docs/_build/html
+          force_orphan: true

.github/workflows/conda-packaging.yml

@@ -5,6 +5,10 @@ on:
   release:
     types: [published]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   conda-packaging:
     name: Conda packaging

.github/workflows/integration.yml

@@ -9,6 +9,10 @@ on:
   schedule:
     - cron: "0 0 * * *"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   run-examples:
     runs-on: ${{ matrix.os }}

.github/workflows/mmg-packaging.yml

@@ -3,6 +3,10 @@ name: Create conda package for mmg
 on:
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   Linux:
     name: Linux

.github/workflows/neper-packaging.yml

@@ -3,6 +3,10 @@ name: Create conda package for neper
 on:
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   Linux:
     name: Linux

.github/workflows/pre-commit.yml

@@ -5,6 +5,10 @@ on:
   push:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   pre-commit:
     runs-on: ubuntu-latest

.github/workflows/pypi-packaging.yml

@@ -7,6 +7,10 @@ on:
   release:
     types: [published]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-n-publish:
     name: Build and publish to PyPI and TestPyPI

.github/workflows/test-conda-package.yml

@@ -3,6 +3,10 @@ name: Test conda package
 on:
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test-linux:
     name: Linux

.pre-commit-config.yaml

@@ -27,12 +27,6 @@ repos:
 #     - id: interrogate
 #       args: [-vv, --fail-under=100, --omit-covered-files]
 
-- repo: https://github.com/keewis/blackdoc
-  rev: v0.3.9
-  hooks:
-  - id: blackdoc
-    files: '\.py$'
-
 - repo: https://github.com/codespell-project/codespell
   rev: v2.3.0
   hooks:

docs/index.rst

@@ -23,6 +23,8 @@ Table of contents
 
    Overview
    Install
+   quick_start
+   tutorials
 
 
 .. toctree::

docs/quick_start.rst

@@ -0,0 +1,144 @@
+.. _RST QuickStart:
+
+Quick-Start Guide
+=================
+
+This guide will help you get started with Microgen quickly. We'll cover the basics of creating shapes, TPMS structures, and exporting your results.
+
+.. jupyter-execute::
+   :hide-code:
+
+   import pyvista
+   pyvista.set_jupyter_backend('static')
+   pyvista.global_theme.background = 'white'
+   pyvista.global_theme.window_size = [600, 400]
+   pyvista.global_theme.axes.show = False
+   pyvista.global_theme.smooth_shading = True
+   pyvista.global_theme.split_sharp_edges = True
+
+
+First Steps
+-----------
+
+Import microgen:
+
+.. jupyter-execute::
+
+   import microgen
+
+
+Creating a Basic TPMS Shape
+---------------------------
+
+Let's create a Gyroid TPMS structure, one of the most common triply periodic minimal surfaces:
+
+.. jupyter-execute::
+
+   gyroid = microgen.Tpms(
+       surface_function=microgen.surface_functions.gyroid,
+       offset=0.3,
+       cell_size=1.0,
+       repeat_cell=2,
+       resolution=20
+   )
+
+   # Get the sheet geometry as a PyVista mesh
+   sheet = gyroid.sheet
+   sheet.plot(color='white')
+
+
+TPMS Part Types
+---------------
+
+Each TPMS can generate different part types:
+
+.. jupyter-execute::
+
+   tpms = microgen.Tpms(
+       surface_function=microgen.surface_functions.gyroid,
+       offset=0.5,
+       resolution=20
+   )
+
+   # Sheet (wall) geometry
+   sheet = tpms.sheet
+
+   # Upper skeletal (network) geometry
+   upper_skeletal = tpms.upper_skeletal
+
+   # Lower skeletal (complementary network) geometry
+   lower_skeletal = tpms.lower_skeletal
+
+   sheet.plot(color='lightblue')
+
+
+Creating Basic Shapes
+---------------------
+
+Microgen provides several basic geometric shapes:
+
+.. jupyter-execute::
+
+   # Create a sphere
+   sphere = microgen.Sphere(center=(0, 0, 0), radius=0.5)
+   sphere_vtk = sphere.generate_vtk()
+   sphere_vtk.plot(color='white')
+
+.. jupyter-execute::
+
+   # Create a box
+   box = microgen.Box(center=(0, 0, 0), dim=(1, 0.5, 0.3))
+   box_vtk = box.generate_vtk()
+   box_vtk.plot(color='white')
+
+.. jupyter-execute::
+
+   # Create a cylinder
+   cylinder = microgen.Cylinder(center=(0, 0, 0), height=1.0, radius=0.3)
+   cylinder_vtk = cylinder.generate_vtk()
+   cylinder_vtk.plot(color='white')
+
+
+Generating CAD Geometry
+-----------------------
+
+To create CAD-compatible solids (for 3D printing or CAD software):
+
+.. code-block:: python
+
+   # Generate the CadQuery shape
+   cad_shape = gyroid.generate(type_part='sheet')
+
+
+Exporting Results
+-----------------
+
+Export to STL (from PyVista mesh):
+
+.. code-block:: python
+
+   sheet.save('gyroid_sheet.stl')
+
+Export to STEP (from CadQuery shape):
+
+.. code-block:: python
+
+   import cadquery as cq
+
+   cad_shape = gyroid.generate(type_part='sheet')
+   cq.exporters.export(cq.Workplane().add(cad_shape), 'gyroid_sheet.step')
+
+Export to VTK:
+
+.. code-block:: python
+
+   sheet.save('gyroid_sheet.vtk')
+
+
+Next Steps
+----------
+
+- Explore the :ref:`RST Geometries` for more shape examples
+- Check the :ref:`RST Tpms` for all available TPMS surfaces
+- Learn about :ref:`RST 3Dop` for repeating and rastering
+- See :ref:`RST Mesh` for meshing capabilities