🎉 init: coordinax-interop-astropy (#482)

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

Author: nstarman

docs/contributing.md

@@ -9,17 +9,17 @@ When opening an issue to report a problem, please try to provide:
 
 ## Contributing Code and Documentation
 
-So you are interested in contributing to the `coordinax`? Excellent! We love
-contributions! `coordinax` is open source, built on open source, and we'd love
-to have you hang out in our community.
+So you are interested in contributing to the {mod}`coordinax`? Excellent! We
+love contributions! {mod}`coordinax` is open source, built on open source, and
+we'd love to have you hang out in our community.
 
 ## How to Contribute, Best Practices
 
-Most contributions to `coordinax` are done via
+Most contributions to {mod}`coordinax` are done via
 [pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
 from GitHub users' forks of the
-[`coordinax` repository](https://github.com/GalacticDynamics/coordinax). If you
-are new to this style of development, check out Astropy's
+[{mod}`coordinax` repository](https://github.com/GalacticDynamics/coordinax). If
+you are new to this style of development, check out {mod}`astropy`'s
 [development workflow](https://docs.astropy.org/en/latest/development/quickstart.html).
 
 Once you open a pull request (which should be opened against the `main` branch,
@@ -38,8 +38,8 @@ following:
   description in the main documentation (in `docs/`).
 
 - **Performance improvements**: if you are making changes that impact
-  `coordinax` performance, consider adding a performance benchmark in `tests`. A
-  maintainer will also be able to run comparative benchmarks to catch
+  {mod}`coordinax` performance, consider adding a performance benchmark in
+  `tests`. A maintainer will also be able to run comparative benchmarks to catch
   performance changes. The PR needs to have the `run-benchmarks` label to run
   the workflow.
 
@@ -48,12 +48,12 @@ following:
 Before being merged, a pull request for a new feature will be reviewed to see if
 it meets the following requirements. If you are unsure about how to meet all of
 these requirements, please submit the PR and ask for help and/or guidance. A
-`coordinax` maintainer will collaborate with you to make sure that the pull
+{mod}`coordinax` maintainer will collaborate with you to make sure that the pull
 request meets the requirements for inclusion in the package:
 
 **Relevance:**
 
-- Is the submission relevant to `coordinax`?
+- Is the submission relevant to {mod}`coordinax`?
 - Does the code perform as expected?
 - If applicable, are references included to the origin source for the algorithm?
 - Has the code been tested against previously existing implementations?
@@ -63,7 +63,7 @@ request meets the requirements for inclusion in the package:
 - Are the coding guidelines followed?
 - Is the code compatible with the supported versions of Python?
 - Are there dependencies other than the run-time dependencies listed in
-  pyproject.toml?
+  `pyproject.toml`?
 
 **Testing:**
 

docs/conventions.md

@@ -2,8 +2,8 @@
 
 ## Naming Conventions
 
-`coordinax` uses a few conventions to make the code more readable and to avoid
-verbosity. Many of these are also found in the [Glossary](glossary.md).
+{mod}`coordinax` uses a few conventions to make the code more readable and to
+avoid verbosity. Many of these are also found in the [Glossary](glossary.md).
 
 - `Abstract...`: a class that is not meant to be instantiated directly, but
   rather to be subclassed. Abstract classes are prefixed with 'Abstract'.
@@ -16,10 +16,10 @@ verbosity. Many of these are also found in the [Glossary](glossary.md).
 
 ## Functional vs Object-Oriented APIs
 
-As `JAX` is function-oriented, but Python is generally object-oriented,
-`coordinax` provides both functional and object-oriented APIs. The functional
-APIs are the primary APIs, but the object-oriented APIs are easy to use and call
-the functional APIs, so lose none of the power.
+As {mod}`JAX` is function-oriented, but Python is generally object-oriented,
+{mod}`coordinax` provides both functional and object-oriented APIs. The
+functional APIs are the primary APIs, but the object-oriented APIs are easy to
+use and call the functional APIs, so lose none of the power.
 
 As an example, consider the following code snippets:
 
@@ -64,16 +64,22 @@ SphericalPos(
 
 `coordinax` uses [multiple dispatch](https://beartype.github.io/plum/) to hook
 into `quax`'s flexible and extensible system to enable custom array-ish objects,
-like {class}`~unxt.quantity.Quantity`, in `JAX`. Also, `coordinax` uses multiple
-dispatch to enable deep interoperability between `coordinax` and other
-libraries, like `astropy` (and anything user-defined).
+like {class}`~unxt.quantity.Quantity`, in {mod}`JAX`. Also, {mod}`coordinax`
+uses multiple dispatch to enable deep interoperability between {mod}`coordinax`
+and other libraries, like {mod}`astropy` (and anything user-defined).
 
-For example, `coordinax` provides a {meth}`~coordinax.vecs.AbstractVector.from_`
-method that can convert an `astropy.Representation` to a
+For example, if {mod}`coordinax-interop-astropy` is installed, {mod}`coordinax`
+registers to {meth}`~coordinax.vecs.AbstractVector.from_` a method that can
+convert an `astropy.Representation` to a
 {class}`~coordinax.vecs.AbstractVector`:
 
-```{code-block} python
+<!-- invisible-code-block: python
+import importlib.util
+-->
+
+<!-- skip: start if(importlib.util.find_spec('coordinax_interop_astropy') is None, reason="coordinax-interop-astropy not installed") -->
 
+```{code-block} python
 >>> import astropy.coordinates as apyc
 >>> import coordinax.vecs as cxv
 
@@ -82,13 +88,15 @@ method that can convert an `astropy.Representation` to a
 <CartesianRepresentation (x, y, z) in m
     (1., 2., 3.)>
 
->>> xq = cxv.CartesianPos3D.from_(aq)  # unxt Quantity
+>>> xq = cxv.CartesianPos3D.from_(aq)
 >>> print(xq)
 <CartesianPos3D: (x, y, z) [m]
     [1. 2. 3.]>
 
 ```
 
+<!-- skip: end -->
+
 This easy interoperability is enabled by multiple dispatch, which allows the
 {meth}`~coordinax.vecs.AbstractVector.from_` method to dispatch to the correct
 implementation based on the types of the arguments.

docs/index.md

@@ -13,6 +13,7 @@ coordinax-api <packages/coordinax-api/index>
 coordinax <self>
 coordinax-astro <packages/coordinax-astro/index>
 coordinax-hypothesis <packages/coordinax-hypothesis/index>
+coordinax-interop-astropy <packages/coordinax-interop-astropy/index>
 ```
 
 ```{toctree}
@@ -41,12 +42,13 @@ interop/*
 ```{toctree}
 :maxdepth: 2
 :hidden:
-:caption: 🔌 API Reference
+:caption: 📘 API Reference
 
 coordinax-api <packages/coordinax-api/api>
 coordinax <api/index.md>
 coordinax-astro <packages/coordinax-astro/api>
 coordinax-hypothesis <packages/coordinax-hypothesis/api>
+coordinax-interop-astropy <packages/coordinax-interop-astropy/api>
 ```
 
 ```{toctree}

docs/packages/coordinax-interop-astropy

@@ -0,0 +1 @@
+../../packages/coordinax-interop-astropy/docs

noxfile.py

@@ -127,7 +127,7 @@ def pytest(s: nox.Session, /, package: PackageEnum) -> None:
 # Documentation
 
 
-@session(uv_groups=["docs"], reuse_venv=True)
+@session(uv_groups=["docs"], uv_extras=["workspace"], reuse_venv=True)
 def docs(s: nox.Session, /) -> None:
     """Build the docs. Pass "--serve" to serve. Pass "-b linkcheck" to check links."""
     parser = argparse.ArgumentParser()

packages/coordinax-api/docs/index.md

@@ -104,11 +104,12 @@ The `coordinax-api` package follows these principles:
 
 Use `coordinax-api` when you:
 
-- Want to implement coordinax protocols in your own package
-- Need coordinax integration without the full coordinax dependency
-- Are building a library that provides vector types compatible with coordinax
+- Want to implement {mod}`coordinax` protocols in your own package
+- Need {mod}`coordinax` integration without the full {mod}`coordinax` dependency
+- Are building a library that provides vector types compatible with
+  {mod}`coordinax`
 
-Use the full `coordinax` package when you:
+Use the full {mod}`coordinax` package when you:
 
 - Need concrete vector implementations (CartesianPos3D, SphericalPos, etc.)
 - Want to perform actual coordinate transformations

packages/coordinax-astro/src/coordinax_astro/__init__.py

@@ -9,10 +9,3 @@
     from .frame_transforms import *
     from .galactocentric import Galactocentric
     from .icrs import ICRS
-
-    # Interoperability. Importing this module will register interop frameworks.
-    # isort: split
-    from . import _interop
-
-# clean up namespace
-del _interop