Support objects.inv

Bug #1453370 reported by PyDeq on 2015-05-09
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Beautiful Soup
Wishlist
Unassigned

Bug Description

Running Sphinx [1] in the nitpicky [2] mode with the intersphinx [3] extension allows one to check whether references in their documentation is correct. E.g. it checks whether the class named `bs4.BeautifulSoup` in this example::

    .. function:: process(document)

       Process an HTML document.

       :param document: the HTML document
       :type document: bs4.BeautifulSoup

really exists. It works by pointing [4] the extension to an `objects.inv` file of the given library. I don't know the format very well but I guess that it contains at least the list of all the documented identifiers/names of the given library. The file is automatically generated by Sphinx [3].

Since BeautifulSoup's documentation doesn't use directives like `.. class::` to document its classes, its `objects.inv` file does not contain references to its classes etc. Would it be possible to use these directives to automatically populate the `objects.inv` file so that other developers can use it for the reference check as described above?

Here is a minimal reproducer:

1. Create a file `test/contents.rst`::

    .. function:: process(document)

       Process an HTML document.

       :param document: the HTML document
       :type document: bs4.BeautifulSoup

2. Create a file `test/conf.py`::

    extensions = ["sphinx.ext.intersphinx"]
    intersphinx_mapping = {"bs4": ("http://www.crummy.com/software/BeautifulSoup/bs4/doc/", None)}

3. Run `sphinx-build -n test test`

So far, you can see this warning in the output: "contents.rst:6: WARNING: py:obj reference target not found: bs4.BeautifulSoup"

[1] http://sphinx-doc.org/
[2] http://sphinx-doc.org/config.html#confval-nitpicky
[3] http://sphinx-doc.org/ext/intersphinx.html
[4] http://sphinx-doc.org/ext/intersphinx.html?highlight=intersphinx#confval-intersphinx_mapping

Changed in beautifulsoup:
importance: Undecided → Wishlist
status: New → Confirmed
Adrián Chaves (gallaecio) wrote :

objects.inv exists, what does not exist is the API reference documentation.

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers