Documentation appears not to link back to source about qiskit-metapackage HOT 10 CLOSED

Thanks @Travis-S - will be looked into as part of #80, as we can take the chance to look into the possibility of linking to the repository directly.

from qiskit-metapackage.

i think this is what @Travis-S wants is some way to open the source code. @Travis-S is this correct?

from qiskit-metapackage.

@jaygambetta Yes. Consider this documentation for a pyQuil program in Forest. If a user wants to read the source code itself, they can click the source link (near the declaration of the class) and are taken to a page where they can read it.

from qiskit-metapackage.

great, i agree. @derivation can you think about the above.

from qiskit-metapackage.

I think this would be much appreciated by users. I'll chat with @diego-plan9 and @lzdanski about how to incorporate this practice. Thanks @Travis-S.

from qiskit-metapackage.

Thanks for the extended feedback and comments, @Travis-S - yes, the way we had it setup previously was very similar to the example you mention: we were generating .html files for each source file (with syntax highlighting, etc) that were linked from the autodoc files (ie. the ones that contain just a description of the functions, arguments, etc). This should be easy to reintroduce (is mostly toggling a flag in the configuration).

What I was trying to suggest was considering, instead of reintroducing those rendered pages as generated .html files, replacing the source links with links to the actual files and lines in github. This might provide users with more context about that particular function (and be able to explore github features and the feature history for those inclined to do so), and maybe have the side effect of sparkling contributing or taking a more active role (on the technical side, it also helps a bit with the size of the documentation, as in the terra docs the rendered .html source files were the biggest culprit, but not a strong argument for it).

from qiskit-metapackage.

@diego-plan9 Absolutely! That would be a great improvement on the original suggestion.

from qiskit-metapackage.

I issued #200 for reintroducing the source link using the original approach (ie. include additional rendered .html that contains the source), aiming for the source links being present in the upcoming major release.

For being able to link to github, it would be worth exploring sphinx.ext.linkcode instead, that offers a linkcode_resolve() function that we can tune to return the proper link. The bits that involve more work are being able to deal with multiple versions and repositories, and linking to the specific lines of code (by default, the extension does not provide details about the line numbers) - a source of inspiration can be the numpy conf.py or similar projects.

from qiskit-metapackage.

@Travis-S is this done in the api documentation now.

from qiskit-metapackage.

from qiskit-metapackage.