https://github.com/dahlia/sphinx-fakeinv

Generate fake Intersphinx inventory
https://github.com/dahlia/sphinx-fakeinv

docs intersphinx python sphinx

Last synced: 5 months ago
JSON representation

Generate fake Intersphinx inventory

• Host: GitHub
• URL: https://github.com/dahlia/sphinx-fakeinv
• Owner: dahlia
• License: gpl-3.0
• Created: 2016-09-18T18:36:04.000Z (about 9 years ago)
• Default Branch: master
• Last Pushed: 2016-09-18T19:46:59.000Z (about 9 years ago)
• Last Synced: 2025-04-01T02:12:52.042Z (7 months ago)
• Topics: docs, intersphinx, python, sphinx
• Language: Python
• Homepage: https://pypi.python.org/pypi/sphinx-fakeinv
• Size: 21.5 KB
• Stars: 5
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
``sphinx-fakeinv``: Generate fake Intersphinx_ inventory

=========================================================

.. image:: https://badge.fury.io/py/sphinx-fakeinv.svg

   :target: https://pypi.python.org/pypi/sphinx-fakeinv

   :alt: Latest PyPI version

.. image:: https://travis-ci.org/dahlia/sphinx-fakeinv.svg

   :alt: Build Status

   :target: https://travis-ci.org/dahlia/sphinx-fakeinv

Sometimes we create so tiny libraries that we don't need write docs using

Sphinx_ for them, but at the same time we may want to link them from

other docs written using Sphinx.

This utility helps us to generate a fake ``objects.inv`` file

(it's also known as Sphinx inventory) so that other Sphinx docs can link

it through the Intersphinx_ extension.

.. _Sphinx: http://www.sphinx-doc.org/

.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

Installation

------------

It's uploaded to PyPI_, so you can install it using ``pip``:

.. code-block:: console

   $ pip install sphinx-fakeinv

.. _PyPI: https://pypi.python.org/pypi/sphinx-fakeinv

Usage

-----

Suppose you've just written a tiny module named ``foobar``.  You can generate

a fake ``objects.inv`` for it by the following command:

.. code-block:: console

   $ sphinx-fakeinv foobar > objects.inv

The ``shinx-fakeinv`` program automatically scans the submodules, subpackages,

and classes/functions/exceptions/variables in all of scanned modules/packages.

(Note that it's aware of ``__all__`` list if there's one.)

If you want to link it from other Sphinx docs, you need to manually add the url

of it (of course you need to upload the generated fake ``objects.inv``

somewhere like gh-pages) to ``intersphinx_mapping`` configuration:

.. code-block:: python

   intersphinx_mapping = {

       'foobar': (

           'https://github.com/example/foobar',            # The project website

           'https://example.github.io/foobar/objects.inv'  # The fake inventory

       ),

   }

That's done!  If you make references to ``foobar`` e.g.:

.. code-block:: rst

   If :mod:`foobar` module is available at runtime this function will uses

   internally :func:`foobar.baz()`.

Links in the above example like ``foobar`` and ``foobar.baz()`` will refer

to ``https://github.com/example/foobar``.

Author and license

------------------

Written by `Hong Minhee`__.  Distributed under GPLv3_ or later.

__ https://hongminhee.org/

.. _GPLv3: http://www.gnu.org/licenses/gpl-3.0.html