Enable "nitpicky" mode on Sphinx

And fix related missing references.

Closes: #929

Makefile

@@ -104,7 +104,7 @@ TAGS:
 
 # DOC: Compile the documentation
 doc:
-	$(MAKE) -C $(DOC_DIR) SPHINXOPTS=-W html
+	$(MAKE) -C $(DOC_DIR) SPHINXOPTS="-n -W" html
 
 linkcheck:
 	$(MAKE) -C $(DOC_DIR) linkcheck

docs/conf.py

@@ -21,7 +21,7 @@
 
 project = 'Factory Boy'
 copyright = '2011-2015, Raphaël Barrois, Mark Sandstrom'
-author = 'adfasf'
+author = 'Raphaël Barrois, Mark Sandstrom'
 
 # The full version, including alpha/beta/rc tags
 release = factory.__version__
@@ -84,6 +84,10 @@
         'https://docs.djangoproject.com/en/dev/',
         'https://docs.djangoproject.com/en/dev/_objects/',
     ),
+    'mongoengine': (
+        'https://mongoengine-odm.readthedocs.io/',
+        None,
+    ),
     'sqlalchemy': (
         'https://docs.sqlalchemy.org/en/latest/',
         'https://docs.sqlalchemy.org/en/latest/objects.inv',

docs/examples.rst

@@ -76,7 +76,7 @@ And now, we'll define the related factories:
 
 
 
-We have now defined basic factories for our :class:`~Account` and :class:`~Profile` classes.
+We have now defined basic factories for our ``Account`` and ``Profile`` classes.
 
 If we commonly use a specific variant of our objects, we can refine a factory accordingly:
 

docs/fuzzy.rst

@@ -354,4 +354,4 @@ They should inherit from the :class:`BaseFuzzyAttribute` class, and override its
         Custom :class:`BaseFuzzyAttribute` subclasses **MUST**
         use :obj:`factory.random.randgen` as a randomness source; this ensures that
         data they generate can be regenerated using the simple state from
-        :meth:`get_random_state`.
+        :meth:`factory.random.get_random_state`.

docs/ideas.rst

@@ -4,6 +4,6 @@ Ideas
 
 This is a list of future features that may be incorporated into factory_boy:
 
-* When a :class:`Factory` is built or created, pass the calling context throughout the calling chain instead of custom solutions everywhere
+* When a :class:`~factory.Factory` is built or created, pass the calling context throughout the calling chain instead of custom solutions everywhere
 * Define a proper set of rules for the support of third-party ORMs
 * Properly evaluate nested declarations (e.g ``factory.fuzzy.FuzzyDate(start_date=factory.SelfAttribute('since'))``)

docs/internals.rst

@@ -57,11 +57,11 @@ First, decide the strategy:
   use the strategy defined at the :attr:`class Meta <Factory.Meta>` level
 
 
-Then, we'll pass the strategy and passed-in overrides to the :meth:`~Factory._generate` method.
+Then, we'll pass the strategy and passed-in overrides to the ``Factory._generate`` method.
 
-.. note:: According to the project road map, a future version will use a :meth:`~Factory._generate_batch` at its core instead.
+.. note:: According to the project road map, a future version will use a ``Factory._generate_batch`` at its core instead.
 
-A factory's :meth:`~Factory._generate` function actually delegates to a ``StepBuilder()`` object.
+A factory's ``Factory._generate`` function actually delegates to a ``StepBuilder()`` object.
 This object will carry the overall "build an object" context (strategy, depth, and possibly other).
 
 
@@ -81,7 +81,7 @@ Instantiating, Step 3: Building the object
 
 1. The ``StepBuilder`` fetches the attributes computed by the ``Resolver``.
 2. It applies renaming/adjustment rules
-3. It passes them to the :meth:`FactoryOptions.instantiate` method, which
+3. It passes them to the ``FactoryOptions.instantiate`` method, which
    forwards to the proper methods.
 4. Post-declaration are applied (in declaration order)
 

docs/introduction.rst

@@ -112,7 +112,7 @@ This is achieved with the :class:`~factory.Sequence` declaration:
     >>> UserFactory()
     <User: user3>
 
-.. note:: For more complex situations, you may also use the :meth:`~factory.@sequence` decorator (note that ``self`` is not added as first parameter):
+.. note:: For more complex situations, you may also use the :meth:`@factory.sequence <factory.sequence>` decorator (note that ``self`` is not added as first parameter):
 
           .. code-block:: python
 
@@ -152,7 +152,7 @@ argument and returning the value for the field:
 
 
 .. note:: For complex cases when you happen to write a specific function,
-          the :meth:`~factory.@lazy_attribute` decorator should be more appropriate.
+          the :meth:`@factory.lazy_attribute <factory.lazy_attribute>` decorator should be more appropriate.
 
 
 LazyAttribute
@@ -185,7 +185,7 @@ taking the object being built and returning the value for the field:
     <User: user2 ([email protected])>
 
 
-.. note:: As for :class:`~factory.Sequence`, a :meth:`~factory.@lazy_attribute` decorator is available:
+.. note:: As for :class:`~factory.Sequence`, a :meth:`@factory.lazy_attribute <factory.lazy_attribute>` decorator is available:
 
 
 .. code-block:: python

docs/orms.rst

@@ -13,7 +13,7 @@ adding dedicated features.
 Django
 ------
 
-.. currentmodule:: factory.django
+.. module:: factory.django
 
 
 The first versions of factory_boy were designed specifically for Django,
@@ -111,11 +111,10 @@ All factories for a Django :class:`~django.db.models.Model` should use the
 
     .. attribute:: skip_postgeneration_save
 
-        Transitional option to prevent
-        :meth:`~factory.django.DjangoModelFactory._after_postgeneration` from
-        issuing a duplicate call to :meth:`~django.db.models.Model.save` on the
-        created instance when :class:`factory.PostGeneration` hooks return a
-        value.
+        Transitional option to prevent :class:`~factory.django.DjangoModelFactory`'s
+        ``_after_postgeneration`` from issuing a duplicate call to
+        :meth:`~django.db.models.Model.save` on the created instance when
+        :class:`factory.PostGeneration` hooks return a value.
 
 
 Extra fields
@@ -167,9 +166,9 @@ Extra fields
 
         :param str from_path: Use data from the file located at ``from_path``,
                               and keep its filename
-        :param file from_file: Use the contents of the provided file object; use its filename
+        :param io.BytesIO from_file: Use the contents of the provided file object; use its filename
                                if available, unless ``filename`` is also provided.
-        :param func from_func: Use function that returns a file object
+        :param Callable from_func: Use function that returns a file object
         :param bytes data: Use the provided bytes as file contents
         :param str filename: The filename for the FileField
 
@@ -200,9 +199,9 @@ Extra fields
 
         :param str from_path: Use data from the file located at ``from_path``,
                               and keep its filename
-        :param file from_file: Use the contents of the provided file object; use its filename
+        :param io.BytesIO from_file: Use the contents of the provided file object; use its filename
                                if available
-        :param func from_func: Use function that returns a file object
+        :param Callable from_func: Use function that returns a file object
         :param str filename: The filename for the ImageField
         :param int width: The width of the generated image (default: ``100``)
         :param int height: The height of the generated image (default: ``100``)
@@ -272,7 +271,7 @@ To work around this problem, use the :meth:`mute_signals()` decorator/context ma
 Mogo
 ----
 
-.. currentmodule:: factory.mogo
+.. module:: factory.mogo
 
 factory_boy supports `Mogo`_-style models, through the :class:`MogoFactory` class.
 
@@ -294,7 +293,7 @@ factory_boy supports `Mogo`_-style models, through the :class:`MogoFactory` clas
 MongoEngine
 -----------
 
-.. currentmodule:: factory.mongoengine
+.. module:: factory.mongoengine
 
 factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngineFactory` class.
 
@@ -312,8 +311,8 @@ factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngin
     * :func:`~factory.Factory.create()` builds an instance through ``__init__`` then
       saves it.
 
-    .. note:: If the :attr:`associated class <factory.FactoryOptions.model` is a :class:`mongoengine.EmbeddedDocument`,
-              the :meth:`~MongoEngineFactory.create` function won't "save" it, since this wouldn't make sense.
+    .. note:: If the :attr:`associated class <factory.FactoryOptions.model>` is a :class:`mongoengine.EmbeddedDocument`,
+              the :class:`~MongoEngineFactory`'s ``create`` function won't "save" it, since this wouldn't make sense.
 
               This feature makes it possible to use :class:`~factory.SubFactory` to create embedded document.
 
@@ -349,7 +348,7 @@ A minimalist example:
 SQLAlchemy
 ----------
 
-.. currentmodule:: factory.alchemy
+.. module:: factory.alchemy
 
 
 Factory_boy also supports `SQLAlchemy`_  models through the :class:`SQLAlchemyModelFactory` class.
@@ -364,12 +363,12 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr:
 
     This class provides the following features:
 
-    * :func:`~factory.Factory.create()` uses :meth:`sqlalchemy.orm.session.Session.add`
+    * :func:`~factory.Factory.create()` uses :meth:`sqlalchemy.orm.Session.add`
 
 
 .. class:: SQLAlchemyOptions(factory.base.FactoryOptions)
 
-    In addition to the usual parameters available in :class:`class Meta <factory.base.FactoryOptions>`,
+    In addition to the usual parameters available in :class:`class Meta <factory.FactoryOptions>`,
     a :class:`SQLAlchemyModelFactory` also supports the following settings:
 
     .. attribute:: sqlalchemy_session
@@ -403,8 +402,8 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr:
         Valid values are:
 
         * ``None``: do nothing
-        * ``'flush'``: perform a session :meth:`~sqlalchemy.orm.session.Session.flush`
-        * ``'commit'``: perform a session :meth:`~sqlalchemy.orm.session.Session.commit`
+        * ``'flush'``: perform a session :meth:`~sqlalchemy.orm.Session.flush`
+        * ``'commit'``: perform a session :meth:`~sqlalchemy.orm.Session.commit`
 
         The default value is ``None``.
 
@@ -413,8 +412,8 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr:
         .. versionadded:: 3.0.0
 
         Fields whose name are passed in this list will be used to perform a
-        :meth:`Model.query.one_or_none() <sqlalchemy.orm.query.Query.one_or_none>`
-        or the usual :meth:`Session.add() <sqlalchemy.orm.session.Session.add>`:
+        :meth:`Model.query.one_or_none() <sqlalchemy.orm.Query.one_or_none>`
+        or the usual :meth:`Session.add() <sqlalchemy.orm.Session.add>`:
 
         .. code-block:: python
 
@@ -516,15 +515,15 @@ there is no "global" session management system.
 The most common pattern when working with unit tests and ``factory_boy``
 is to use `SQLAlchemy`_'s :class:`sqlalchemy.orm.scoping.scoped_session`:
 
-* The test runner configures some project-wide :class:`~sqlalchemy.orm.scoping.scoped_session`
+* The test runner configures some project-wide :class:`~sqlalchemy.orm.scoped_session`
 * Each :class:`~SQLAlchemyModelFactory` subclass uses this
-  :class:`~sqlalchemy.orm.scoping.scoped_session` as its :attr:`~SQLAlchemyOptions.sqlalchemy_session`
+  :class:`~sqlalchemy.orm.scoped_session` as its :attr:`~SQLAlchemyOptions.sqlalchemy_session`
 * The :meth:`~unittest.TestCase.tearDown` method of tests calls
-  :meth:`Session.remove <sqlalchemy.orm.scoping.scoped_session.remove>`
+  :meth:`Session.remove <sqlalchemy.orm.scoped_session.remove>`
   to reset the session.
 
 .. note:: See the excellent :ref:`SQLAlchemy guide on scoped_session <sqlalchemy:unitofwork_contextual>`
-          for details of :class:`~sqlalchemy.orm.scoping.scoped_session`'s usage.
+          for details of :class:`~sqlalchemy.orm.scoped_session`'s usage.
 
           The basic idea is that declarative parts of the code (including factories)
           need a simple way to access the "current session",
@@ -536,7 +535,7 @@ is to use `SQLAlchemy`_'s :class:`sqlalchemy.orm.scoping.scoped_session`:
 
 Here is an example layout:
 
-- A global (test-only?) file holds the :class:`~sqlalchemy.orm.scoping.scoped_session`:
+- A global (test-only?) file holds the :class:`~sqlalchemy.orm.scoped_session`:
 
 .. code-block:: python
 
@@ -568,7 +567,7 @@ Here is an example layout:
         name = factory.Sequence(lambda n: "User %d" % n)
 
 
-- The test runner configures the :class:`~sqlalchemy.orm.scoping.scoped_session` when it starts:
+- The test runner configures the :class:`~sqlalchemy.orm.scoped_session` when it starts:
 
 .. code-block:: python
 

docs/recipes.rst

@@ -89,7 +89,7 @@ use a :class:`~factory.RelatedFactory` declaration:
         )
 
 
-When a :class:`UserFactory` is instantiated, factory_boy will call
+When a ``UserFactory`` is instantiated, factory_boy will call
 ``UserLogFactory(user=that_user, action=...)`` just before returning the created ``User``.
 
 
@@ -101,7 +101,7 @@ using a :class:`~django.db.models.OneToOneField` from the ``Profile`` to the ``U
 
 A typical way to create those profiles was to hook a post-save signal to the ``User`` model.
 
-Prior to version 2.9, the solution to this was to override the :meth:`~factory.Factory._generate` method on the factory.
+Prior to version 2.9, the solution to this was to override the ``factory.Factory._generate`` method on the factory.
 
 Since version 2.9, the :meth:`~factory.django.mute_signals` decorator should be used:
 
@@ -216,8 +216,8 @@ Many-to-many relation with a 'through'
 --------------------------------------
 
 
-If only one link is required, this can be simply performed with a :class:`RelatedFactory`.
-If more links are needed, simply add more :class:`RelatedFactory` declarations:
+If only one link is required, this can be simply performed with a :class:`~factory.RelatedFactory`.
+If more links are needed, simply add more :class:`~factory.RelatedFactory` declarations:
 
 .. code-block:: python