New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Does GHDLs documentation provide an intersphinx file? #200

Closed
Paebbels opened this Issue Nov 12, 2016 · 6 comments

Comments

Projects
None yet
3 participants
@Paebbels
Member

Paebbels commented Nov 12, 2016

I would like to link some parts of PoC's documentation to GHDLs documentation. Therefore Sphinx offers the intersphinx extension. What's GHDLs URL to the intersphinx inventory file?

@tgingold

This comment has been minimized.

Member

tgingold commented Nov 12, 2016

On 12/11/16 05:46, Patrick Lehmann wrote:

I would like to link some parts of my documentation to GHDLs
documentation. Therefore Sphinx offers the intersphinx extension. What's
GHDLs URL to the intersphinx inventory file?

I am not aware about intersphinx. Any patch is welcome!

@Paebbels

This comment has been minimized.

Member

Paebbels commented Nov 12, 2016

I found that Sphinx creates the object.inv in _build/html. So it should be accessible at http://ghdl.readthedocs.io/en/latest/objects.inv. (Link) My browser can load a file ...

So this should answer my URL and linking question.

# Sphinx inventory version 2
# Project: GHDL
# Version: 0.33
# The remainder of this file is compressed using zlib.
xÚ¥XKoÛ8�¾ëW�Ø^¹@¯{KÛt�À�Œ¤h÷FÐ"

Hmmm the GHDL documentation is still 0.33. I'm working on a Python snippet for Sphinx's conf.py to extract the current version number from Git (latest tag name). So the Documentation displays the correct version number matching the underlying source code / docs state.

The next question is now, which identifiers does GHDLs documentation provide?
How can I decompress zlib content (as I understood it's stream compressed, so no zip content).

Two other notes regarding Sphinx and ReadTheDocs:

  • I see you linked the index page genindex.html at the bottom of the start page. I found a way to reference it from the navigation bar:

    Workaround steps:

    1. Create a genindex.rst in you documentation root folder.
    2. Add a headline like "Index" to the created file.
    3. Reference genindex from your toctree directive.

    This creates and references a genindex.html file in the root directory, which is later overwritten by Sphinx when generating the real index page.

  • You can create "parts" (LaTeX terminology / chapter headlines) in your navigation bar, by using multiple toctree directives and setting the option :caption: Part Title.

    .. toctree::
       :caption: Introduction
    
       chapter1
       chapter2
    
    .. toctree::
       :caption: Appendix
    
       chapter3
       chapter4

    See the latest PoC-Library Documentation.

@Paebbels

This comment has been minimized.

Member

Paebbels commented Nov 13, 2016

Hmmm, I still can't resolve symbols from GHDL. Sphinx prints out that GHDL's inventory file was downloaded, but references gave warnings like this: index.rst:74: WARNING: unknown option: ghdl:--ieee

Normally, one could cross-reference with this syntax:

:option:`ghdl:--ieee`
:option:`GHDL options <ghdl:--ieee>`

In contrast to these problems, I can reference classes in the Python documentation (also using Sphinx).
See this example: http://poc-library.readthedocs.io/en/release/PyInfrastructure/PoC.html#PoC.main for a reference to argparse.

You can open and analyze GHDLs inventory files by:

  1. Running python -m sphinx.ext.intersphinx "http://ghdl.readthedocs.io/en/latest/objects.inv"
  2. Using this Python script: inventory.py

The decoded information looks correct:

std:option
[...]
    :std:option:--ieee:
        :Link:  :std:option:`--ieee <ghdl:--ieee>`
        :Domain:    GHDL
        :Version:   0.33
        :URL:   Invoking_GHDL.html#cmdoption--ieee
        :Title: -
[...]

Moreover is shows the link, which I used for testing.

@Paebbels Paebbels changed the title from Does GHDLs documentation provide an intersphing file? to Does GHDLs documentation provide an intersphinx file? Dec 11, 2016

@1138-4EB

This comment has been minimized.

Contributor

1138-4EB commented Mar 1, 2017

Little update:

  • This syntax works, and allows to reference and link external sections:
:ref:`GHDL Roadmap <ghdl:CHANGE:Roadmap>`
  • This allows to reference external program options, but no link is created:
:option:`ghdl:--ieee`
@1138-4EB

This comment has been minimized.

Contributor

1138-4EB commented Mar 2, 2017

Well, in the end, it was a bug in Sphinx, not anything we were doing wrong. It will be fixed in 1.5.4, see sphinx-doc/sphinx#3487
Meanwhile, we can use the syntax shown in my previous comment, so that no change is required when the new version is released.

I think this issue can be closed now. @Paebbels?

@Paebbels

This comment has been minimized.

Member

Paebbels commented Mar 2, 2017

Sometimes new people need to report old bugs ... I already asked for updates on 2822 ...

@Paebbels Paebbels closed this Mar 2, 2017

@Paebbels Paebbels added the Question label May 31, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment