Wie Sie richtig schreiben, Verweise auf externe Dokumentationen mit intersphinx?

Ich gab weitere versuche, auf den Versuch zu verstehen, den Inhalt eines objects.inv Datei und hoffentlich dieses mal habe ich geprüft numpy und h5py statt nur OpenCV ist eine.

, Wie zu Lesen, ein intersphinx Inventar-Datei

Trotz der Tatsache, dass ich konnte nicht finden, dass irgendetwas nützliches zum Lesen der Inhalte eines object.inv - Datei, es ist eigentlich sehr einfach mit dem intersphinx Modul.

from sphinx.ext import intersphinx
import warnings


def fetch_inventory(uri):
    """Read a Sphinx inventory file into a dictionary."""
    class MockConfig(object):
        intersphinx_timeout = None  # type: int
        tls_verify = False

    class MockApp(object):
        srcdir = ''
        config = MockConfig()

        def warn(self, msg):
            warnings.warn(msg)

    return intersphinx.fetch_inventory(MockApp(), '', uri)


uri = 'http://docs.python.org/2.7/objects.inv'

# Read inventory into a dictionary
inv = fetch_inventory(uri)
# Or just print it
intersphinx.debug(['', uri])

Datei-Struktur (numpy)

Nach der Besichtigung numpy ist, können Sie sehen, dass Schlüssel-domains:

[u'np-c:function',
 u'std:label',
 u'c:member',
 u'np:classmethod',
 u'np:data',
 u'py:class',
 u'np-c:member',
 u'c:var',
 u'np:class',
 u'np:function',
 u'py:module',
 u'np-c:macro',
 u'np:exception',
 u'py:method',
 u'np:method',
 u'np-c:var',
 u'py:exception',
 u'np:staticmethod',
 u'py:staticmethod',
 u'c:type',
 u'np-c:type',
 u'c:macro',
 u'c:function',
 u'np:module',
 u'py:data',
 u'np:attribute',
 u'std:term',
 u'py:function',
 u'py:classmethod',
 u'py:attribute']

Können Sie sehen, wie Sie können schreiben Sie Ihre cross-Referenz, wenn man sich die Inhalte einer bestimmten Domäne. Zum Beispiel py:class:

{u'numpy.DataSource': (u'NumPy',
  u'1.9',
  u'http://docs.scipy.org/doc/numpy/reference/generated/numpy.DataSource.html#numpy.DataSource',
  u'-'),
 u'numpy.MachAr': (u'NumPy',
  u'1.9',
  u'http://docs.scipy.org/doc/numpy/reference/generated/numpy.MachAr.html#numpy.MachAr',
  u'-'),
 u'numpy.broadcast': (u'NumPy',
  u'1.9',
  u'http://docs.scipy.org/doc/numpy/reference/generated/numpy.broadcast.html#numpy.broadcast',
  u'-'),
  ...}

Also hier :class:`numpy.DataSource` wie erwartet funktionieren wird.

h5py

Im Fall von h5py, die domains sind:

[u'py:attribute', u'std:label', u'py:method', u'py:function', u'py:class']

und wenn man sich die py:class domain:

{u'AttributeManager': (u'h5py',
  u'2.5',
  u'http://docs.h5py.org/en/latest/high/attr.html#AttributeManager',
  u'-'),
 u'Dataset': (u'h5py',
  u'2.5',
  u'http://docs.h5py.org/en/latest/high/dataset.html#Dataset',
  u'-'),
 u'ExternalLink': (u'h5py',
  u'2.5',
  u'http://docs.h5py.org/en/latest/high/group.html#ExternalLink',
  u'-'),
 ...}

Deshalb konnte ich nicht machen, es funktioniert nach wie numpy Referenzen. Also ein guter Weg, um zu formatieren wäre :class:`h5py:Dataset`.

OpenCV

OpenCV das Inventar-Objekt scheint fehlerhaft. Wo ich erwarten würde, zu finden, die domains gibt es eigentlich 902 Funktions-Signaturen:

[u':',
 u'AdjusterAdapter::create(const',
 u'AdjusterAdapter::good()',
 u'AdjusterAdapter::tooFew(int',
 u'AdjusterAdapter::tooMany(int',
 u'Algorithm::create(const',
 u'Algorithm::getList(vector<string>&',
 u'Algorithm::name()',
 u'Algorithm::read(const',
 u'Algorithm::set(const'
 ...]

... und wenn, nehmen wir den ersten Wert:

{u'Ptr<AdjusterAdapter>': (u'OpenCV',
  u'2.4',
  u'http://docs.opencv.org/2.4/detectorType)',
  u'ocv:function 1 modules/features2d/doc/common_interfaces_of_feature_detectors.html#$ -')}

Ich bin mir ziemlich sicher, dass es dann unmöglich zu schreiben OpenCV Querverweise mit dieser Datei...

Abschluss

Dachte ich intersphinx generiert die objects.inv auf der Grundlage des Inhalts der Dokumentation Projekt in einer standard Weg, das scheint nicht der Fall zu sein.
Als Ergebnis scheint es, dass die richtige Art und Weise zu schreiben, cross-Referenzen-API abhängig und man sollte untersuchen ein spezielles Inventar-Objekt tatsächlich zu sehen, was verfügbar ist.

Wie zu verwenden OpenCV 2.4 (cv2) intersphinx

Inspiriert von @Gall die Antwort, ich wollte zum vergleichen der Inhalte der OpenCV & numpy inventory-Dateien. Ich konnte nicht sphinx.ext.intersphinx.fetch_inventory arbeiten von ipython, aber der folgende Code funktioniert:

curl http://docs.opencv.org/2.4/objects.inv | tail -n +5 | zlib-flate -uncompress > cv2.inv
curl https://docs.scipy.org/doc/numpy/objects.inv | tail -n +5 | zlib-flate -uncompress > numpy.inv

numpy.WR Zeilen wie diese:

numpy.ndarray py:class 1 reference/generated/numpy.ndarray.html#$ -

in der Erwägung, dass cv2.WR Zeilen wie diese:

cv2.imread ocv:pyfunction 1 modules/highgui/doc/reading_and_writing_images_and_video.html#$ -

Also vermutlich Sie würde link auf die OpenCV-docs mit :ocv:pyfunction:`cv2.imread` statt :py:function:`cv2.imread`. Sphinx mag es nicht, wenn:

WARNING: Unknown interpretiert text-Rolle "ocv:pyfunction".

Ein bisschen Googlen ergab, dass die OpenCV-Projekt hat seine eigenen "ocv" sphinx domain: https://github.com/opencv/opencv/blob/2.4/doc/ocv.py -- vermutlich, weil Sie brauchen, um das Dokument C -, C++ - und Python-APIs, die alle zur gleichen Zeit.

Um es zu verwenden, speichern Sie ocv.py neben Ihrem Sphinx conf.py, und ändern Sie Ihre conf.py:

sys.path.insert(0, os.path.abspath('.'))
import ocv
extensions = [
    'ocv',
]
intersphinx_mapping = {
    'cv2': ('http://docs.opencv.org/2.4/', None),
}

In den ersten Dateien, die Sie brauchen, um zu sagen :ocv:pyfunc:`cv2.imread` (nicht :ocv:pyfunction:).

Sphinx druckt einige Warnungen ( unparseable C++ definition: u'cv2.imread' ), aber die generierte html-Dokumentation sieht eigentlich ok mit einem link zu http://docs.opencv.org/2.4/modules/highgui/doc/reading_and_writing_images_and_video.html#cv2.imread. Sie können Bearbeiten ocv.py und entfernen Sie die Zeile, die gedruckt, Warnung.

Eine weitere Möglichkeit zur Prüfung der objects.inv Datei mit der sphobjinv Modul.

Können Sie suchen lokalen oder auch remote inventory Dateien (mit fuzzy-matching). Zum Beispiel mit scipy:

$ sphobjinv suggest -t 90 -u https://docs.scipy.org/doc/scipy/reference/objects.inv "signal.convolve2d"

Remote inventory found.

:py:function:`scipy.signal.convolve2d`
:std:doc:`generated/scipy.signal.convolve2d`

Beachten Sie, dass Sie verwenden müssen, um :py:func: und nicht :py:function: (ich würde gerne wissen, warum).