Intersphinx

[hynek]

Use Sphinx’s own intersphinx files and APIs to get all symbol names. That’s both more robust and gives us a better introspection into the actual types of symbols.

Todos:

• front page as reported in Cannot detect Gevent's documentation format #27 (comment)
• bring coverage back to 100%

Should fix #27 and #25.

[coveralls]

Coverage decreased (-0.25%) when pulling 041ee5a on intersphinx into 8d524aa on master.

[coveralls]

Coverage decreased (-0.25%) when pulling 68e4e21 on intersphinx into 8d524aa on master.

[coveralls]

Coverage increased (+0.04%) when pulling 3e67005 on intersphinx into 8d524aa on master.

[coveralls]

Coverage increased (+0.04%) when pulling 3e67005 on intersphinx into 8d524aa on master.

[coveralls]

Coverage increased (+0.04%) when pulling f6691a7 on intersphinx into 8d524aa on master.

[coveralls]

Coverage increased (+0.04%) when pulling 3e35f80 on intersphinx into 8d524aa on master.

[winny-]

Same result as of 3e35f80 — search not working nor index entries in the tree list on the left.

I am assuming flag -f is sufficient to install over a docset.

[hynek]

It is, although sometimes caching does weird stuff. Ideally try with a new name.

• If that doesn’t help: does it say Converting intersphinx docs or Converting sphinx docs?
• If the latter: does doc2dash --version say doc2dash 1.3.0?
• If yes, does the docs directory contain an “objects.inv”?

[winny-]

Converting intersphinx docs, doc2dash 1.3.0 is correct, and I see an objects.inv.

➜  pandora-apidoc git:(master) doc2dash --version
doc2dash 1.3.0
➜  pandora-apidoc git:(master) find . -name objects.inv
./_build/html/objects.inv
➜  pandora-apidoc git:(master) doc2dash -n Pandora2 -A _build/html/
Converting intersphinx docs from "_build/html" to "/Users/winston/Library/Application Support/doc2dash/DocSets/Pandora2.docset".
Parsing HTML...
Creating database...
Added 0 index entries.
Adding table of contents meta data...
Adding to dash...

[hynek]

Could you provide me with an archive of your built docs? Thanks!

[winny-]

https://www.dropbox.com/s/4kkfr2iszvwfz67/pandora-apidoc.tar.gz includes git repository, compiled sphinx doc, and dash docset.

[hynek]

Thank you for your help!

I looked into the objects.inv and turns out the API functions/methods/symbols aren’t properly defined. They’re all within std:label. A proper one would be for example py:method or something.

FWIW, doc2dash ignores the py: part.

But this is definitely an issue with the documentation and nothing I can fix within doc2dash, sorry!

[winny-]

Is it possible to extend doc2dash to use a different namespace in objects.inv for non-Python sphinx docsets? Is it the norm to use the py: namespace outside of Python?

Thank you for clarifying the issue with the docset I am using.

[hynek]

As said, doc2dash (in this branch) explicitly ignores the part before the colon. So c:function And py:function are both just functions. OTOH std:label are semantically nothing. Other docs use it for misc bookmarks for instance.

That said, you can always write own parsers of course. :) But in this case I really think it's the docset that should be fixed.