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"
+  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: |
+          cd docs
+          make dirhtml
+
+      - 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,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - cep-devel
   pull_request:
 
 concurrency:

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,71 @@
+name: menuinst-docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - alabaster=0.7.12
+  - 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
+  - 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
+  - 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-copybutton=0.5.0
+  - sphinx-design=0.3.0
+  - sphinx-sitemap=2.2.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
+  - 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/conf.py

@@ -0,0 +1,85 @@
+# Copyright (C) 2022 Anaconda, Inc
+# SPDX-License-Identifier: BSD-3-Clause
+# 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 = html_title = "menuinst"
+copyright = "2022, menuinst contributors"
+author = "menuinst contributors"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.mermaid",
+    "sphinx_sitemap",
+    "sphinx_design",
+    "sphinx_copybutton",
+]
+
+myst_heading_anchors = 3
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "substitution",
+    "tasklist",
+]
+
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+
+html_css_files = [
+    "css/custom.css",
+]
+
+# Serving the robots.txt since we want to point to the sitemap.xml file
+html_extra_path = ["robots.txt"]
+
+html_theme_options = {
+    "github_url": "https://github.com/conda/menuinst",
+    "collapse_navigation": True,
+    "navigation_depth": 1,
+    "use_edit_page_button": True,
+    "show_toc_level": 1,
+    "navbar_align": "left",
+    "header_links_before_dropdown": 1,
+    # "announcement": "<p>This is the documentation for menuinst!</p>",
+}
+
+html_context = {
+    "github_user": "conda",
+    "github_repo": "menuinst",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+# We don't have a locale set, so we can safely ignore that for the sitemaps.
+sitemap_locales = [None]
+# We're hard-coding stable here since that's what we want Google to point to.
+sitemap_url_scheme = "{link}"

docs/source/defining-shortcuts.md

@@ -0,0 +1,70 @@
+# Define your own shortcuts
+
+`menuinst` takes JSON configuration files as its input.
+The minimal structure is a dictionary with four keys
+
+- `$schema`: The JSON-schema standard version
+- `$id`: The version of the menuinst configuration, as a JSON schema URL
+- `menu_name`: The name for this group of menu items
+- `menu_items`: A list of dictionaries, each defining the settings for one shortcut / menu item. Each menu item must define, at least, the following keys:
+    - `name`: The name for this specific shortcut.
+    - `command`: A list of strings detailing how to launch the application.
+    - `platforms`: A dictionary with up to three keys. All of them are optional but you must at least define one. The presence of a key with a non-`null` value enables the shortcut for that platform. If you don't include any, shortcuts will not be created. Available keys are:
+        - `linux`
+        - `osx`
+        - `win`
+
+## Minimal example 
+
+A minimal example to launch Python's `turtle` module would be:
+
+```json
+{
+    "$schema": "https://json-schema.org/draft-07/schema",
+    "$id": "https://schemas.conda.io/menuinst-1.schema.json",
+    "menu_name": "Python {{ PY_VER }}",
+    "menu_items": [
+        {
+            "name": "Launch Turtle",
+            "command": ["python", "-m", "turtle"],
+            "platforms": {
+                "linux": {},
+                "osx": {},
+                "win": {},
+            }
+        }
+    ]
+}
+```
+
+This is not using any customization options or advanced features.
+It's the bare minimum to make it work: a name, the command, and the target platforms.
+
+If you want to learn more, check this reference for full details on the available fields and settings for each platform.
+The JSON configurations follow a well-defined schema documented at {ref}`schema`.
+
+```{tip}
+Note how the `menu_name` is using a placeholder `{{ PY_VER }}`.
+`menuinst` supports Jinja-like variables. 
+The full list of available placeholders is available at {ref}`placeholders`.
+```
+
+## Integrate with `conda` packages
+
+To enable the native `conda` integrations, instruct the `conda-build` scripts to place the `menuinst` JSON configuration files in `$PREFIX/Menu`.
+
+On Linux and macOS this usually looks like:
+
+```bash
+# On your build.sh
+mkdir -p "${PREFIX}/Menu"
+cp "${RECIPE_DIR}/menu.json" "${PREFIX}/Menu/${PKG_NAME}_menu.json"
+```
+
+For Windows:
+
+```batch
+:: On bld.bat
+mkdir "%PREFIX%\Menu"
+copy /Y "%RECIPE_DIR%\menu.json" "%PREFIX%\Menu\%PKG_NAME%_menu.json"
+```