diff --git a/.flake8 b/.flake8 index edd6e8e2..785d1707 100644 --- a/.flake8 +++ b/.flake8 @@ -5,5 +5,5 @@ max-line-length = 80 max-complexity = 10 docstring-convention = google per-file-ignores = tests/*:S101 -rst-roles = const,class,func,meth,mod +rst-roles = const,class,func,meth,mod,ref rst-directives = deprecated diff --git a/docs/conf.py b/docs/conf.py index 4e8a93c5..de574058 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,9 +7,14 @@ copyright = f"{datetime.now().year}, {author}" extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", "sphinx.ext.napoleon", ] autodoc_typehints = "description" html_theme = "furo" html_favicon = "images/favicon.png" html_logo = "images/logo.png" +intersphinx_mapping = { + "nox": ("https://nox.thea.codes/en/stable", None), + "pip": ("https://pip.pypa.io/en/stable", None), +} diff --git a/src/nox_poetry/sessions.py b/src/nox_poetry/sessions.py index 7bcc6cfb..afa74b5c 100644 --- a/src/nox_poetry/sessions.py +++ b/src/nox_poetry/sessions.py @@ -15,14 +15,11 @@ def session(*args: Any, **kwargs: Any) -> Any: - """Drop-in replacement for the nox.session_ decorator. + """Drop-in replacement for the :func:`nox.session` decorator. Use this decorator instead of ``@nox.session``. Session functions are passed - :class:`Session` instead of ``nox.Session``; otherwise, the decorators work - exactly the same. - - .. _nox.session: - https://nox.thea.codes/en/stable/config.html#nox.session + :class:`Session` instead of :class:`nox.sessions.Session`; otherwise, the + decorators work exactly the same. Args: args: Positional arguments are forwarded to ``nox.session``. @@ -67,31 +64,24 @@ def install(self, *args: str, **kwargs: Any) -> None: """Install packages into a Nox session using Poetry. This function installs packages into the session's virtual environment. It - is a wrapper for `nox.sessions.Session.install`_, whose positional - arguments are command-line arguments for `pip install`_, and whose keyword - arguments are the same as those for `nox.sessions.Session.run`_. + is a wrapper for :meth:`nox.sessions.Session.install`, whose positional + arguments are command-line arguments for :ref:`pip install`, and whose keyword + arguments are the same as those for :meth:`nox.sessions.Session.run`. If a positional argument is ".", a wheel is built using :meth:`build_package`, and the argument is replaced with the file URL returned by that function. Otherwise, the argument is forwarded unchanged. - In addition, a `constraints file`_ is generated for the package - dependencies using :meth:`export_requirements`, and passed to ``pip - install`` via its ``--constraint`` option. This ensures that any package - installed will be at the version specified in Poetry's lock file. - - .. _pip install: https://pip.pypa.io/en/stable/reference/pip_install/ - .. _nox.sessions.Session.install: - https://nox.thea.codes/en/stable/config.html#nox.sessions.Session.install - .. _nox.sessions.Session.run: - https://nox.thea.codes/en/stable/config.html#nox.sessions.Session.run - .. _constraints file: - https://pip.pypa.io/en/stable/user_guide/#constraints-files + In addition, a :ref:`constraints file ` is generated + for the package dependencies using :meth:`export_requirements`, and + passed to ``pip install`` via its ``--constraint`` option. This ensures + that any package installed will be at the version specified in Poetry's + lock file. Args: args: Command-line arguments for ``pip install``. kwargs: Keyword-arguments for ``session.install``. These are the same - as those for `nox.sessions.Session.run`_. + as those for :meth:`nox.sessions.Session.run`. """ from nox_poetry.core import Session_install @@ -128,10 +118,11 @@ def installroot( This function installs the package located in the current directory into the session's virtual environment. - A constraints file is generated for the package dependencies using - :meth:`export_requirements`, and passed to ``pip install`` via its - ``--constraint`` option. This ensures that core dependencies are installed - using the versions specified in Poetry's lock file. + A :ref:`constraints file ` is generated for the + package dependencies using :meth:`export_requirements`, and passed to + :ref:`pip install` via its ``--constraint`` option. This ensures that + core dependencies are installed using the versions specified in Poetry's + lock file. Args: distribution_format: The distribution format, either wheel or sdist. @@ -155,18 +146,16 @@ def installroot( def export_requirements(self) -> Path: """Export a requirements file from Poetry. - This function uses `poetry export`_ to generate a `requirements file`_ - containing the project dependencies at the versions specified in - ``poetry.lock``. The requirements file includes both core and development - dependencies. + This function uses `poetry export`_ to generate a :ref:`requirements + file ` containing the project dependencies at the + versions specified in ``poetry.lock``. The requirements file includes + both core and development dependencies. The requirements file is stored in a per-session temporary directory, together with a hash digest over ``poetry.lock`` to avoid generating the file when the dependencies have not changed since the last run. .. _poetry export: https://python-poetry.org/docs/cli/#export - .. _requirements file: - https://pip.pypa.io/en/stable/user_guide/#requirements-files Returns: The path to the requirements file. @@ -211,7 +200,7 @@ def build_package( class _SessionProxy: - """Proxy for nox.Session.""" + """Proxy for :class:`nox.sessions.Session`.""" def __init__(self, session: nox.Session) -> None: """Initialize.""" @@ -223,10 +212,7 @@ def __getattr__(self, name: str) -> Any: class Session(_SessionProxy): - """Proxy for nox.sessions.Session_, passed to user-defined session functions. - - .. _nox.sessions.Session: - https://nox.thea.codes/en/stable/config.html#nox.sessions.Session + """Proxy for :class:`nox.sessions.Session`, passed to session functions. This class overrides :meth:`session.install `, and provides Poetry-related