Add API reference (cjolowicz#113)

* Expand docstrings for the API reference

* Export core.build_package

* Include patch in API reference

* Remove handcrafted API reference from README

* Add furo 2020.9.28-beta.8

* Use furo theme

* Remove table of contents in API reference

* Minor cleanup in README

* Restructure reference.rst

* Configure rst-roles for flake8-rst-docstrings

* Fix RST306 (unknown target name)

.flake8

@@ -5,3 +5,4 @@ max-line-length = 80
 max-complexity = 10
 docstring-convention = google
 per-file-ignores = tests/*:S101
+rst-roles = const,class,func,mod

README.rst

@@ -65,7 +65,8 @@ use the following command to install this package into the same environment:
 Usage
 -----
 
-Import ``nox_poetry.patch`` at the top of your ``noxfile.py``, and you're good to go.
+Import ``nox_poetry.patch`` at the top of your ``noxfile.py``.
+
 ``nox-poetry`` intercepts calls to ``session.install``
 and uses Poetry to export a `constraints file`_ and build the package behind the scenes.
 All packages installed in Nox sessions must be managed as dependencies in Poetry.
@@ -90,8 +91,8 @@ More precisely, the session builds a wheel from the local package,
 installs the wheel as well as the ``pytest`` package, and
 invokes ``pytest`` to run the test suite against the installation.
 
-If you prefer a less magical, more explicit approach,
-you can also invoke ``nox_poetry.install(session, ...)`` instead of ``session.install(...)``.
+If you prefer a more explicit approach,
+you can also invoke ``nox_poetry.install`` instead of ``session.install``.
 Pass ``nox_poetry.WHEEL`` or ``nox_poetry.SDIST`` to build and install the local package
 using the specified distribution format.
 
@@ -161,24 +162,6 @@ For more details, take a look at `this article`__.
 __ https://cjolowicz.github.io/posts/hypermodern-python-03-linting/#managing-dependencies-in-nox-sessions-with-poetry
 
 
-API
----
-
-``nox_poetry.install(session, *args, **kwargs)``:
-   Install packages into a Nox session using Poetry.
-
-   The ``nox_poetry.install`` function
-   installs dependencies into a Nox session,
-   using the versions specified in Poetry's lock file.
-   The function arguments are the same as those for `nox.sessions.Session.install`_:
-   The first argument is the ``Session`` object,
-   and the remaining arguments are command-line arguments for `pip install`_,
-   typically just the package or packages to be installed.
-   The constants ``nox_poetry.WHEEL`` and ``nox_poetry.SDIST``
-   are replaced by a distribution archive built for the local package.
-   Keyword arguments are the same as those for `nox.sessions.Session.run`_.
-
-
 Contributing
 ------------
 

docs/conf.py

@@ -7,3 +7,4 @@
 copyright = f"{datetime.now().year}, {author}"
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
 autodoc_typehints = "description"
+html_theme = "furo"

docs/reference.rst

@@ -1,13 +1,25 @@
-Reference
-=========
+API Reference
+=============
 
-.. contents::
-    :local:
-    :backlinks: none
+.. automodule:: nox_poetry
 
+Constants
+.........
 
-nox_poetry
-----------
+.. autodata:: WHEEL
+.. autodata:: SDIST
 
-.. automodule:: nox_poetry
-   :members:
+Functions
+.........
+
+.. autofunction:: install
+.. autofunction:: build_package
+.. autofunction:: export_requirements
+.. autofunction:: nox_poetry.core.patch
+
+Modules
+.......
+
+**nox_poetry.patch**
+
+.. automodule:: nox_poetry.patch

docs/requirements.txt

@@ -1 +1,2 @@
 sphinx==3.2.1
+furo==2020.9.28b8

noxfile.py

@@ -156,7 +156,7 @@ def xdoctest(session: Session) -> None:
 def docs_build(session: Session) -> None:
     """Build the documentation."""
     args = session.posargs or ["docs", "docs/_build"]
-    session.install(".", "sphinx")
+    session.install(".", "sphinx", "furo")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():
@@ -169,7 +169,7 @@ def docs_build(session: Session) -> None:
 def docs(session: Session) -> None:
     """Build and serve the documentation with live reloading on file changes."""
     args = session.posargs or ["--open-browser", "docs", "docs/_build"]
-    session.install(".", "sphinx", "sphinx-autobuild")
+    session.install(".", "sphinx", "sphinx-autobuild", "furo")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():

pyproject.toml

@@ -41,6 +41,7 @@ pep8-naming = "^0.11.1"
 darglint = "^1.5.4"
 reorder-python-imports = "^2.3.5"
 pre-commit-hooks = "^3.2.0"
+furo = "^2020.9.28-beta.8"
 
 [tool.coverage.paths]
 source = ["src", "*/site-packages"]

src/nox_poetry/__init__.py

@@ -1,13 +1,35 @@
-"""Using Poetry in Nox sessions."""
+"""Using Poetry in Nox sessions.
+
+This package provides a facility to monkey-patch Nox so ``session.install``
+installs packages at the versions specified in the Poetry lock file, and
+``"."`` is replaced by a wheel built from the local package.
+See :mod:`nox_poetry.patch`.
+
+It also provides helper functions that allow more fine-grained control:
+
+- :func:`install`
+- :func:`build_package`
+- :func:`export_requirements`
+
+Two constants are defined to specify the format for distribution archives:
+
+- :const:`WHEEL`
+- :const:`SDIST`
+"""
+from nox_poetry.core import build_package
 from nox_poetry.core import export_requirements
 from nox_poetry.core import install
 from nox_poetry.poetry import DistributionFormat
 
 
+#: A wheel archive.
 WHEEL = DistributionFormat.WHEEL
+
+#: A source archive.
 SDIST = DistributionFormat.SDIST
 
 __all__ = [
+    "build_package",
     "export_requirements",
     "install",
     "SDIST",