mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
ececc4dcfe
The autodoc_mock_imports option requires to explicitly declare *every*
external module and sub-module that are imported by the documented code.
This is not practical as the list can become very large and must be
maintained as the code changes.
Also, the mocking is minimal which causes errors when compiling the
docs. For example, if you declare:
autodoc_mock_imports = ['django.template']
And try to document a module:
.. automodule:: my.lib.util
Which contains this code:
from django.template import Library
register = Library()
The following error occurs:
File ".../my/lib/util.py" line 2
register = Library()
TypeError: 'object' object is not callable
Other similar errors can occur such as "TypeError: 'object' object has
no len".
To address these limitations, only require to declare the top-level
module that should be mocked:
autodoc_mock_imports = ['django']
Will mock "django" but also any sub-module: "django.template",
"django.contrib", etc.
Also, make the mocked modules yield more complete dummy objects to avoid
these TypeError problems.
Behind the scenes, it uses the python import hooks mechanism specified
in PEP 302.
Signed-off-by: Robin Jarry <robin@jarry.cc>
.. image:: https://img.shields.io/pypi/v/sphinx.svg
:target: http://pypi.python.org/pypi/sphinx
.. image:: https://readthedocs.org/projects/sphinx/badge/
:target: http://www.sphinx-doc.org/
:alt: Documentation Status
.. image:: https://travis-ci.org/sphinx-doc/sphinx.svg?branch=master
:target: https://travis-ci.org/sphinx-doc/sphinx
=================
README for Sphinx
=================
This is the Sphinx documentation generator, see http://www.sphinx-doc.org/.
Installing
==========
Install from PyPI to use stable version::
pip install -U sphinx
Install from PyPI to use beta version::
pip install -U --pre sphinx
Install from newest dev version in stable branch::
pip install git+https://github.com/sphinx-doc/sphinx@stable
Install from newest dev version in master branch::
pip install git+https://github.com/sphinx-doc/sphinx
Install from cloned source::
pip install .
Install from cloned source as editable::
pip install -e .
Release signatures
==================
Releases are signed with following keys:
* `498D6B9E <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x102C2C17498D6B9E>`_
* `5EBA0E07 <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x1425F8CE5EBA0E07>`_
Reading the docs
================
You can read them online at <http://www.sphinx-doc.org/>.
Or, after installing::
cd doc
make html
Then, direct your browser to ``_build/html/index.html``.
Testing
=======
To run the tests with the interpreter available as ``python``, use::
make test
If you want to use a different interpreter, e.g. ``python3``, use::
PYTHON=python3 make test
Continuous testing runs on travis: https://travis-ci.org/sphinx-doc/sphinx
Contributing
============
See `CONTRIBUTING.rst`__
.. __: CONTRIBUTING.rst