mkdocs (#933)

* docs

* readded

* trim environment

.github/workflows/build_docs.yaml

@@ -0,0 +1,69 @@
+name: docs
+
+on:
+  workflow_dispatch:
+  push:
+  pull_request:
+
+jobs:
+
+  build_docs:
+    runs-on: ubuntu-latest
+    env:
+      TARGET_PLATFORM: emscripten-wasm32
+      GITHUB_OWNER: "emscripten-forge"
+    strategy:
+      fail-fast: false
+      matrix:
+        emsdk_ver: ["3.1.45"]
+
+    steps:
+      ################################################################
+      # SETUP
+      ################################################################
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      ################################################################
+      # CONFIG
+      ################################################################
+      - uses: prefix-dev/[email protected]
+        with:
+          pixi-version: v0.20.1
+      - run: |
+          pixi run docs-build -d docs_build
+
+      ################################################################
+      # upload to github pages
+      ################################################################
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs_build
+
+  deploy:
+    # only run on main branch
+    if: github.ref == 'refs/heads/main' && github.repository == 'emscripten-forge/recipes'
+
+    # Add a dependency to the build job
+    needs: build_docs
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      contents: read   # to read the Pages artifact
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3 # or specific "vX.X.X" version tag for this action

docs/adding_packages.md

@@ -0,0 +1,3 @@
+# Adding packages
+
+To add a new package to emscripten-forge, just create a Pull Request in this repository.

docs/index.md

@@ -0,0 +1,80 @@
+# Introduction
+
+<!-- conda-forge does not (yet) support emscripten was a plattform. emscripten forge fills this gap -->
+
+Emscripten-forge is a GitHub [organization](https://github.com/emscripten-forge)/[repository](https://github.com/emscripten-forge/recipes) containing  [conda recipes](https://github.com/emscripten-forge/recipes) for the `emscripten-wasm32` platform.
+Conda-forge does not (yet) support the `emscripten-wasm32` platform. `emscripten-forge` fills this gap by providing a channel with conda packages for the `emscripten-wasm32` platform.
+
+
+The recipe repository not only stores the recipe, but also builds and upload the recipe 
+with github actions to the `emscripten-forge` channel on [quetz](https://beta.mamba.pm/channels/emscripten-forge)
+
+
+## Recipe format
+
+Typically, a recipe is directory with a `recipe.yaml` file that contains the information needed to build a package
+and optionally an additonal `build.sh` script that is executed during the build process.
+
+#### recipe.yaml
+
+The recipe.yaml file may look like this:
+```yaml
+context:
+  version: "2022.1.18" # the version of the package
+  name: "regex"        # the name of the package
+
+package:
+  name: ${{ name }}          # use the context variables defined above
+  version: ${{ version }}    # use the context variables defined above
+
+source:
+  # the url is formed from a "template" with the context variables
+  url: https://pypi.io/packages/source/r/${{name}}/${{name}}-${{ version }}.tar.gz
+  sha256: 97f32dc03a8054a4c4a5ab5d761ed4861e828b2c200febd4e46857069a483916
+
+build:
+  number: 0
+
+requirements:
+  build:
+    - python
+    - cross-python_${{target_platform}}
+    - ${{ compiler("c") }}
+    - pip
+  host:
+    - python
+  run:
+    - python
+
+# to test a python package, we need to use the pytester package.
+# this will run pytests in a headless browser
+tests:
+  - script: pytester
+    requirements:
+      build:
+        - pytester
+      run:
+        - pytester-run
+    files:
+      recipe:
+        - test_regex.py
+
+
+about:
+  homepage: https://bitbucket.org/mrabarnett/mrab-regex
+  license: Apache-2.0
+  summary: Alternative regular expression module, to replace re
+
+extra:
+  recipe-maintainers:
+    - DerThorsten
+
+```
+### build.sh
+The bash script may look like this:
+```bash
+#!/bin/bash
+
+export LDFLAGS="-s MODULARIZE=1  -s LINKABLE=1  -s EXPORT_ALL=1 -s WASM=1 -std=c++14 -s SIDE_MODULE=1 -sWASM_BIGINT"
+${PYTHON} -m pip install .
+```

docs/local_builds.md

@@ -0,0 +1,56 @@
+# Local builds
+
+
+## Local with `pixi`
+
+To build a package locally, the easiest way is to use `pixi` (see [/pixi.sh/latest/#installation](https://pixi.sh/latest/#installation) for installation instructions).
+Pixi will under the hood use `rattler-build` to build the package.
+
+```bash
+# this only needs to be done once
+pixi run setup 
+# this builds the package
+pixi run build-emscripten-wasm32-pkg recipes/recipes_emscripten/regex
+```
+
+## Local builds with `rattler-build`
+We recommend using the `pixi` command to build packages locally. However, if you want to use `rattler-build` directly, you can do so with the following steps:
+
+
+### create the environment
+Create a new conda environment from `ci_env.yml` and install playwright in this environment:
+ On a Linux / MacOS this can be done with:
+```bash
+micromamba create -n emscripten-forge -f ci_env.yml --yes
+micromamba activate emscripten-forge
+``` 
+
+
+**All further steps should be executed in this environment.**
+Ie if you open a new terminal, you have to activate the environment again with `micromamba activate emscripten-forge`.
+
+### Setup emsdk
+
+ We currently need a patched version of emsdk. This is because emscripten had some regressions in the `3.1.45` release wrt. dynamic loading of shared libraries. We use the `./emsdk/setup_emsdk.sh` which takes
+ two arguments: the emsdk version and the path where emsdk should be installed.
+ In this example we choose `~/emsdk` as the installation path. You have to use version `3.1.45`.
+
+```bash
+./emsdk/setup_emsdk.sh 3.1.45 ~/emsdk
+```
+
+### Build compiler packages / meta packages:
+
+This is only needed for MacOS. On Linux, the compiler packages are already built and available in the `emscripten-forge` channel.
+
+```bash
+rattler-build build --recipe recipes/recipes/emscripten_emscripten-wasm32/rattler_recipe.yaml   -c https://repo.mamba.pm/emscripten-forge -c conda-forge -c microsoft -m conda_build_config.yaml
+rattler-build build --recipe recipes/recipes/cross-python_emscripten-wasm32/rattler_recipe.yaml -c https://repo.mamba.pm/emscripten-forge -c conda-forge -c microsoft -m conda_build_config.yaml
+rattler-build build --recipe recipes/recipes/pytester/rattler_recipe.yaml                       -c https://repo.mamba.pm/emscripten-forge -c conda-forge -c microsoft -m conda_build_config.yaml
+```
+
+### Build packages with `rattler-build`:
+
+```bash
+rattler-build build  --recipe recipes/recipes_emscripten/regex/rattler_recipe.yaml  --target-platform=emscripten-wasm32 -c https://repo.mamba.pm/emscripten-forge -c conda-forge -c microsoft -m conda_build_config.yaml
+```

mkdocs.yml

@@ -0,0 +1,36 @@
+site_name: Emscripten-forge
+theme:
+  name: material
+
+  palette:
+
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default 
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences

pixi.toml

@@ -6,12 +6,8 @@ authors = ["DerThorsten <[email protected]>"]
 channels = ["conda-forge"]
 platforms = ["osx-arm64", "linux-64"]
 
-
-[dependencies]
-python = "3.11.*"
-
 ############################################
-# SETUP EMSDK / EMSCRIPTEN
+# setup-emsdk feature / tasks
 ############################################
 [feature.feature_setup_emsdk]
 [feature.feature_setup_emsdk.dependencies]
@@ -22,7 +18,7 @@ outputs = ["emscripten_forge_emsdk_install/emsdk_env.sh"]
 
 
 ############################################
-# RATTLER BUILD TASKS
+# rattler-build feature / tasks
 ############################################
 [feature.feature_rattler_build]
 [feature.feature_rattler_build.dependencies]
@@ -50,12 +46,9 @@ outputs = ["output/noarch/pytester-*.tar.bz2"]
 depends_on = ["setup-emsdk"] 
 
 
-
 [feature.feature_rattler_build.tasks.setup]
-cmd = ["echo","setup all done"]
 depends_on = ["build-emscripten-compiler-pkg", "build-cross-python-pkg", "build-pytester-pkg"]
 
-
 [feature.feature_rattler_build.tasks.build-emscripten-wasm32-pkg]
 cmd = [
     "python",
@@ -65,9 +58,29 @@ cmd = [
     "explicit",
     "--emscripten-wasm32",
 ]
-env = { FORCE_RATTLER = "1" }
 
 
+############################################
+# documentation feature / tasks
+############################################
+[feature.feature_documentation]
+[feature.feature_documentation.dependencies]
+python = "3.11.*"
+mkdocs = ">=1.6.0"
+mkdocs-material = ">=9.5.2"
+
+[feature.feature_documentation.tasks.docs-serve]
+cmd = ["mkdocs", "serve"]
+
+[feature.feature_documentation.tasks.docs-build]
+cmd = ["mkdocs", "build"]
+
+
+############################################
+# environments
+############################################
+
 [environments]
 setup-emsdk-env = ["feature_setup_emsdk"]
-rattler-build-env = ["feature_rattler_build"]
+rattler-build-env = ["feature_rattler_build"]
+documentation-env = ["feature_documentation"]

recipes/recipes_emscripten/regex/recipe.yaml

@@ -23,24 +23,22 @@ requirements:
     - python
   run:
     - python
-  
+
 tests:
   - script: pytester
     requirements:
       build:
-        - pytester >= 0.9.0
+        - pytester
       run:
-        - pytester-run >= 0.9.0
+        - pytester-run
     files:
       recipe:
         - test_regex.py
 
 
 about:
   homepage: https://bitbucket.org/mrabarnett/mrab-regex
-  license: Python-2.0
-  license_file: LICENSE.txt
-  license_family: PSF
+  license: Apache-2.0
   summary: Alternative regular expression module, to replace re
 
 extra: