Add documentation for the CEP prototype

.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+name: Docs
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches:
+      # - main
+      - cep-devel
+  pull_request:
+    branches:
+      # - main
+      - cep-devel
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: pages-${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: menuinst-docs
+          environment-file: docs/environment.yml
+          python-version: '3.11'
+          auto-activate-base: false
+
+      - name: Build Documentation
+        run: |
+          pip install -e .
+          cd docs
+          make dirhtml SPHINXOPTS="-W --keep-going -n"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: 'docs/_build/dirhtml'
+
+  pages:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: [docs]
+
+    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/tests.yml

@@ -4,7 +4,15 @@ on:
   push:
     branches:
       - main
+      - cep-devel
+    paths-ignore:
+      - 'docs/**'
   pull_request:
+    branches:
+      - main
+      - cep-devel
+    paths-ignore:
+      - 'docs/**'
 
 concurrency:
   # Concurrency group that uses the workflow name and PR number if available

docs/Makefile

@@ -0,0 +1,24 @@
+# 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
+SPHINXAUTOBUILD   ?= sphinx-autobuild
+SOURCEDIR         = source
+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
+
+livehtml:
+	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# 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/environment.yml

@@ -0,0 +1,76 @@
+name: menuinst-docs
+channels:
+  - conda-forge
+dependencies:
+  - alabaster=0.7.12
+  - autodoc-pydantic=1.8.0
+  - babel=2.11.0
+  - beautifulsoup4=4.11.1
+  - brotlipy=0.7.0
+  - bzip2=1.0.8
+  - ca-certificates=2022.12.7
+  - certifi=2022.12.7
+  - cffi=1.15.1
+  - charset-normalizer=2.1.1
+  - colorama=0.4.6
+  - cryptography=38.0.3
+  - docutils=0.19
+  - idna=3.4
+  - imagesize=1.4.1
+  - importlib-metadata=5.1.0
+  - jinja2=3.1.2
+  - libffi=3.4.2
+  - libsqlite=3.40.0
+  - libzlib=1.2.13
+  - linkify-it-py=2.0.0
+  - livereload=2.6.3
+  - markdown-it-py=2.1.0
+  - markupsafe=2.1.1
+  - mdit-py-plugins=0.3.1
+  - mdurl=0.1.0
+  - myst-parser=0.18.1
+  - ncurses=6.3
+  - openssl=3.0.7
+  - packaging=21.3
+  - pip=22.3.1
+  - pycparser=2.21
+  - pydantic=1.10.4
+  - pydata-sphinx-theme=0.12.0
+  - pygments=2.13.0
+  - pyopenssl=22.1.0
+  - pyparsing=3.0.9
+  - pysocks=1.7.1
+  - python=3.11.0
+  - python_abi=3.11
+  - pytz=2022.6
+  - pyyaml=6.0
+  - readline=8.1.2
+  - requests=2.28.1
+  - setuptools=65.5.1
+  - six=1.16.0
+  - snowballstemmer=2.2.0
+  - soupsieve=2.3.2.post1
+  - sphinx=5.3.0
+  - sphinx-autobuild=2021.3.14
+  - sphinx-copybutton=0.5.0
+  - sphinx-design=0.3.0
+  - sphinx-sitemap=2.2.1
+  - sphinx-tabs=3.4.1
+  - sphinxcontrib-applehelp=1.0.2
+  - sphinxcontrib-devhelp=1.0.2
+  - sphinxcontrib-htmlhelp=2.0.0
+  - sphinxcontrib-jsmath=1.0.1
+  - sphinxcontrib-mermaid=0.7.1
+  - sphinxcontrib-qthelp=1.0.3
+  - sphinxcontrib-serializinghtml=1.1.5
+  - tk=8.6.12
+  - tornado=6.2
+  - typing-extensions=4.4.0
+  - typing_extensions=4.4.0
+  - tzdata=2022f
+  - uc-micro-py=1.0.1
+  - urllib3=1.26.13
+  - wheel=0.38.4
+  - xz=5.2.6
+  - yaml=0.2.5
+  - zipp=3.10.0

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_static/css/custom.css

@@ -0,0 +1,15 @@
+html {
+    --pst-font-size-base: 14px;
+}
+
+html[data-theme="light"] {
+    --pst-color-primary: #025C02;
+    --pst-color-secondary: #3EB049;
+    --pst-color-link-hover: #3EB049;
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: #3EB049;
+    --pst-color-secondary: #025C02;
+    --pst-color-link-hover: #025C02;
+}

docs/source/conda.md

@@ -0,0 +1,88 @@
+# Integrations with conda
+
+While it can be used as a Python library on its own,
+`menuinst` has been designed to work closely with `conda`.
+
+## Installing shortcuts from `conda` packages
+
+```{tip}
+If you want to learn how to create shortcuts for `conda` packages you are building and maintaining, check {doc}`defining-shortcuts`.
+```
+
+`menuinst` integrates natively with `conda`, so as an end user you don't need to do anything to enable it. 
+If a package is shipping a `menuinst`-compatible shortcut, it will be detected at installation time, and `conda` will invoke `menuinst` on its own.
+
+If you want to change the default behavior, there are some command-line flags you can use:
+
+- `--shortcuts` instructs `conda` to create shortcuts if present (default behavior).
+- `--no-shortcuts` can be used to disable the creation of all shortcuts in that command.
+
+These options can also be set in your `.condarc` configuration. Choose one of:
+
+```yaml
+shortcuts: true   # default
+shortcuts: false  # equivalent to always using --no-shortcuts
+```
+
+```{note}
+`mamba` has limited support for menuinst. For more information, follow these issues:
+
+- https://github.com/mamba-org/mamba/issues/1316
+- https://github.com/mamba-org/mamba/issues/923
+```
+
+### Removing shortcuts
+
+The shortcuts created by `menuinst` will be removed automatically by `conda` when you uninstall the associated package from an environment.
+
+```{warning}
+`conda` has a known issue with environment removals. If you run `conda env remove -n <YOUR_ENV>`, the pre-uninstall actions will NOT be executed, which means that `menuinst` won't be invoked and the shortcut artifacts won't be removed. To clear an environment fully in a clean way, you'd need to run `conda remove -n <YOUR_ENV> --all`.
+```
+
+## Adding shortcuts to `conda` packages
+
+To enable the native `conda` integrations, instruct the `conda-build` scripts to place the `menuinst` JSON configuration files in `$PREFIX/Menu`.
+
+
+````{tabs}
+
+```{code-tab} yaml meta.yaml (noarch)
+build:
+  noarch: python
+  number: 0
+  script:
+    - mkdir -p "{{ PREFIX }}/Menu"
+    - cp "{{ RECIPE_DIR }}/menu.json" "{{ PREFIX }}/Menu/{{ PKG_NAME }}_menu.json"
+```
+
+```{code-tab} bash build.sh (Linux and macOS)
+mkdir -p "${PREFIX}/Menu"
+cp "${RECIPE_DIR}/menu.json" "${PREFIX}/Menu/${PKG_NAME}_menu.json"
+```
+
+```{code-tab} batch bld.bat (Windows)
+mkdir "%PREFIX%\Menu"
+copy /Y "%RECIPE_DIR%\menu.json" "%PREFIX%\Menu\%PKG_NAME%_menu.json"
+```
+````
+
+````{tip}
+Use string substitution tools to automatically replace the version on your shortcuts:
+
+With this JSON file:
+
+```json
+{
+    "$schema": "https://json-schema.org/draft-07/schema",
+    "$id": "https://schemas.conda.io/menuinst-1.schema.json",
+    "menu_name": "my_application (__PKG_VERSION__)",
+    "menu_items": ["..."]
+}
+```
+
+Use `sed` like this:
+
+```bash
+$ sed "s/__PKG_VERSION__/${PKG_VERSION}/g" "${RECIPE_DIR}/menu.json" > "${PREFIX}/Menu/${PKG_NAME}_menu.json"
+```
+````