Add docs

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "*"
+  pull_request:
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+  workflow_dispatch:
+
+concurrency:
+  # Concurrency group that uses the workflow name and PR number if available
+  # or commit SHA as a fallback. If a new build is triggered under that
+  # concurrency group while a previous build is running it will be canceled.
+  # Repeated pushes to a PR will cancel all previous builds, while multiple
+  # merges to main will not cancel.
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@v0.6.0
+        with:
+          environments: docs
+      - name: Setup project
+        run: |
+          pixi run --environment docs dev
+      - name: Build docs
+        run: pixi run docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docs/_build/dirhtml'
+
+  pages:
+    runs-on: ubuntu-latest
+    if: false
+    # disable til moved to conda-incubator
+    # 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/test.yml

@@ -44,12 +44,15 @@ jobs:
         with:
           fetch-depth: 0
       - uses: prefix-dev/setup-pixi@v0.6.0
+        with:
+          environments: ${{ env.PIXI_ENV_NAME }}
       - name: Setup project
         run: |
           pixi run --environment ${{ env.PIXI_ENV_NAME }} dev
           echo "channels: [conda-forge]" > .pixi/envs/${{ env.PIXI_ENV_NAME }}/.condarc
           pixi run --environment ${{ env.PIXI_ENV_NAME }} conda info
       - name: Run tests
         run: pixi run --environment ${{ env.PIXI_ENV_NAME }} test --basetemp=${{ runner.os == 'Windows' && 'D:\\temp' || runner.temp }}
-      - name: Build recipe
+      - name: Build recipe (${{ env.PIXI_ENV_NAME }})
+        if: matrix.python-version == '3.10'
         run: pixi run build

.gitignore

@@ -129,4 +129,4 @@ dmypy.json
 .pyre/
 
 # pixi
-.pixi/
+.pixi/

.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+# disable autofixing PRs, commenting "pre-commit.ci autofix" on a pull request triggers a autofix
+ci:
+  autofix_prs: false
+# generally speaking we ignore all vendored code as well as tests data
+# TODO: Restore index and solver exclude lines before merge
+exclude: |
+  (?x)^(
+    tests/data/.* |
+    conda_pypi/data/.* |
+    pixi.lock
+  )$
+repos:
+  # generic verification and formatting
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      # standard end of line/end of file cleanup
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      # ensure syntaxes are valid
+      - id: check-toml
+      - id: check-yaml
+        exclude: |
+          (?x)^(
+            (conda\.)?recipe/meta.yaml
+          )
+      # catch git merge/rebase problems
+      - id: check-merge-conflict
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.16.0
+    hooks:
+      # auto format Python codes within docstrings
+      - id: blacken-docs
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.4
+    hooks:
+      # lint & attempt to correct failures (e.g. pyupgrade)
+      - id: ruff
+        args: [--fix]
+      # compatible replacement for black
+      - id: ruff-format
+  - repo: meta
+    # see https://pre-commit.com/#meta-hooks
+    hooks:
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+  - repo: local
+    hooks:
+      - id: git-diff
+        name: git diff
+        entry: git diff --exit-code
+        language: system
+        pass_filenames: false
+        always_run: true

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# How to contribute
+
+You'll need a copy of `pixi` and `git` in your machine. Then:
+
+1. Clone this repo to disk.
+2. `pixi run test` to run the tests. Choose your desired Python version by picking the adequate environment.
+3. `pixi run docs` to build the docs and `pixi run serve` to serve them in your browser.
+4. `pixi run lint` to run the pre-commit linters and formatters.

README.md

@@ -2,7 +2,21 @@
 
 Better PyPI interoperability for the conda ecosystem.
 
+## What is this?
+
 Includes:
 
 - `conda pip`: A subcommand that wraps `pip` to make it work with `conda` in a better way.
 - Adds `EXTERNALLY-MANAGED` to your environments.
+
+## Why?
+
+Mixing conda and PyPI is often discouraged in the conda ecosystem.
+There are only a handful patterns that are safe to run. This tool
+aims to provide a safer way of keeping your conda environments functional
+while mixing it with PyPI dependencies. Refer to the [documentation](docs/)
+for more details.
+
+## Contributing
+
+Please refer to [`CONTRIBUTING.md`](/CONTRIBUTING.md).

conda_pypi/cli.py

@@ -1,6 +1,7 @@
 """
 conda pip subcommand for CLI
 """
+
 from __future__ import annotations
 
 import argparse
@@ -69,7 +70,12 @@ def execute(args: argparse.Namespace) -> int:
     from conda.common.io import Spinner
     from conda.models.match_spec import MatchSpec
     from .dependencies import analyze_dependencies
-    from .main import (validate_target_env, ensure_externally_managed, run_conda_install, run_pip_install)
+    from .main import (
+        validate_target_env,
+        ensure_externally_managed,
+        run_conda_install,
+        run_pip_install,
+    )
     from .utils import get_prefix
 
     prefix = get_prefix(args.prefix, args.name)

conda_pypi/plugin.py

@@ -3,6 +3,7 @@
 from .cli import configure_parser, execute
 from .main import ensure_target_env_has_externally_managed
 
+
 @plugins.hookimpl
 def conda_subcommands():
     yield plugins.CondaSubcommand(
@@ -19,4 +20,4 @@ def conda_post_commands():
         name="conda-pypi-ensure-target-env-has-externally-managed",
         action=ensure_target_env_has_externally_managed,
         run_for={"install", "create", "update", "remove"},
-    )
+    )

conda_pypi/utils.py

@@ -60,14 +60,15 @@ def get_externally_managed_path(prefix: os.PathLike = None) -> Iterator[Path]:
         if not found:
             raise ValueError("Could not locate EXTERNALLY-MANAGED file")
 
+
 def pypi_spec_variants(spec_str: str) -> Iterator[str]:
     yield spec_str
     spec = MatchSpec(spec_str)
     seen = {spec_str}
     for name_variant in (
         spec.name.replace("-", "_"),
         spec.name.replace("_", "-"),
-    ):  
+    ):
         if name_variant not in seen:  # only yield if actually different
             yield str(MatchSpec(spec, name=name_variant))
             seen.add(name_variant)

docs/_static/css/custom.css

@@ -0,0 +1,7 @@
+/**
+ * This rule is here to avoid the scrollbar appearing when this
+ * is not hosted on ReadTheDocs
+ */
+ #rtd-footer-container {
+    display: none;
+}

docs/conf.py

@@ -0,0 +1,105 @@
+# 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 = "conda-pypi"
+copyright = "2024, conda-pypi contributors"
+author = "conda-pypi 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",
+    "sphinx_sitemap",
+    "sphinx_design",
+    "sphinx_copybutton",
+    "sphinx_reredirects",
+]
+
+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 = "conda_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 = {
+    "navigation_depth": -1,
+    "use_edit_page_button": True,
+    "navbar_center": ["navbar_center"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/conda-incubator/conda-pypi",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Element",
+            "url": "https://matrix.to/#/#conda_conda:gitter.im",
+            "icon": "_static/element_logo.svg",
+            "type": "local",
+        },
+        {
+            "name": "Discourse",
+            "url": "https://conda.discourse.group/",
+            "icon": "fa-brands fa-discourse",
+            "type": "fontawesome",
+        },
+    ],
+}
+
+html_context = {
+    "github_user": "conda-incubator",
+    "github_repo": "conda-pypi",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+html_baseurl = "https://conda-incubator.github.io"
+
+# 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}"
+
+# -- For sphinx_reredirects ------------------------------------------------
+
+redirects = {}

docs/index.md

@@ -0,0 +1,8 @@
+# conda-pypi
+
+Welcome to the conda-pypi documentation!
+
+```{toctree}
+quickstart
+why
+```