Cleanup documentation

docs/index.rst

@@ -1,8 +1,3 @@
-.. dessinemoi documentation master file, created by
-   sphinx-quickstart on Tue May 25 18:21:12 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 :hide-toc:
 
 Dessine-moi
@@ -22,17 +17,14 @@ Dessine-moi
 .. image:: https://img.shields.io/readthedocs/dessinemoi
    :target: https://dessinemoi.readthedocs.io
 
-.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json
-    :target: https://rye-up.com
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json
+    :target: https://rye.astral.sh
     :alt: Rye
 
 .. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
     :target: https://github.com/astral-sh/ruff
     :alt: Ruff
 
-.. image:: https://img.shields.io/badge/code%20style-black-black
-   :target: https://github.com/psf/black
-
 *S'il vous plaît, dessine-moi un mouton.*
 
 Motivation
@@ -45,16 +37,16 @@ born from the need to create dynamically object trees from nested dictionaries
 Features
 --------
 
-- Create a ``Factory`` object and register types to it.
+- Create a :class:`.Factory` object and register types to it.
 - Use dictionaries to create objects from the factory.
-- Create ``attrs``-compatible converters to automatically convert dictionaries
+- Create *attrs*-compatible converters to automatically convert dictionaries
   to instances of registered types.
 - Customise factories to your needs.
 
 Getting started
 ---------------
 
-*Dessine-moi* requires Python 3.8+ and depends on ``attrs``. It is tested with
+*Dessine-moi* requires Python 3.8+ and depends on *attrs*. It is tested with
 Pytest.
 
 Install from PyPI in your virtual environment:

docs/rst/api.rst

@@ -3,20 +3,11 @@
 API Reference
 =============
 
-``Factory``
------------
-
 .. autoclass:: dessinemoi.Factory
    :members:
 
-``FactoryRegistryEntry``
-------------------------
-
 .. autoclass:: dessinemoi.FactoryRegistryEntry
    :members:
 
-``LazyType``
-------------
-
 .. autoclass:: dessinemoi.LazyType
    :members:

docs/rst/usage.rst

@@ -26,7 +26,7 @@ strings, to Python types. Our factory has currently an empty registry:
 Register types to the factory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Let's define a new Python type. For convenience, we will work with the ``attrs``
+Let's define a new Python type. For convenience, we will work with the *attrs*
 library, but *Dessine-moi* does not require you to use it. Let's define a simple
 class:
 
@@ -102,9 +102,9 @@ keyword argument.
 Instantiate registered types
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Once a type is registered, it can be instantiated using the :meth:`~.Factory.new`
-method. If constructed class's constructor expects arguments, the ``args`` and
-``kwargs`` arguments will forward them appropriately:
+Once a type is registered, it can be instantiated using the
+:meth:`~.Factory.create` method. If the constructed class's constructor expects
+arguments, the ``args`` and ``kwargs`` arguments will forward them appropriately:
 
 .. doctest::
 
@@ -162,13 +162,13 @@ Convert objects
 ^^^^^^^^^^^^^^^
 
 *Dessine-moi*'s factories implement converters which can be used as part of the
-``attrs`` conversion step. In its most straightforward form, the
+*attrs* conversion step. In its most straightforward form, the
 :meth:`~.Factory.convert` method operates on a ``value`` argument.
 
 * If ``value`` is not a dictionary, :meth:`~.Factory.convert` returns it
   unchanged.
 * If ``value`` is a dictionary, :meth:`~.Factory.convert` queries its ``type``
-  entry for a type ID and uses it to call :meth:`~.Factory.new`.
+  entry for a type ID and uses it to call :meth:`~.Factory.create`.
 
   .. doctest::
 
@@ -179,7 +179,7 @@ Convert objects
    :class: note
 
    * :meth:`~.Factory.convert` takes a ``allowed_cls`` argument and uses it
-     exactly as :meth:`~.Factory.new` does.
+     exactly as :meth:`~.Factory.create` does.
    * Dictionary conversion won't work with classes expected non kw-only fields.
    * If a ``dict_constructor`` is associated to the registered type, it will be
      used to create the object instead of the default constructor.
@@ -232,7 +232,7 @@ simply referenced by a :class:`.LazyType` instance.
    >>> factory.registry
    {'datetime': FactoryRegistryEntry(cls=LazyType(mod='datetime', attr='datetime'), dict_constructor=None)}
 
-If we call :meth:`Factory.create`, the target type is imported and returned:
+If we call :meth:`.Factory.create`, the target type is imported and returned:
 
 .. doctest::
 

src/dessinemoi/_core.py

@@ -310,8 +310,14 @@ def alias(self, type_id: str, alias_id: str, overwrite_id: bool = False) -> None
         :param alias_id:
             Created alias ID.
 
-        :raises ValueError:
+        :param overwrite_id:
+            If ``True`` and ``alias_id`` is already registered, the existing
+            alias is redefined; else, a :class:`.ValueError` is raised.
 
+        :raises ValueError:
+            If the new alias cannot be registered, either because the target
+            type is not registered, or because the alias exists and is protected
+            against overwrites.
 
         .. versionadded:: 22.2.0
         """