Add links to externally hosted source code for documented symbols #188
Conversation
doc/conf.py
Outdated
| @@ -56,6 +56,11 @@ | |||
|
|
|||
| hawkmoth_root = os.path.join(os.path.abspath(os.path.dirname(__file__)), '../test/examples') | |||
|
|
|||
| source_uri = 'https://github.com/jnikula/hawkmoth/tree/{version}/test/examples/{{source}}#L{{line}}' | |||
| source_version = version if len(version.split('.')) == 3 else 'master' | |||
There was a problem hiding this comment.
Wondering if we should have an intermediate fallback to a specific hash revision instead of using a branch name which is moving target. But I guess it's fine for the current use case.
There was a problem hiding this comment.
That requires looking at git, and opens up more problems. I'd revisit that later.
I did notice the VERSION file does not have v prefix, but the tags do, so I fixed that.
|
I noticed some weirdness in the line numbers, also in warnings. Probably related to how docstring adds/removes lines. I'll look into it before merging this one. |
Fix some issues in line number references. Take into account stripping blank lines from the comments and adding header lines before the comments. Take into account that ViewList uses 0-based line numbers. With this, error reporting should have more accurate line numbers.
Sphinx has sphinx.ext.viewcode and sphinx.ext.linkcode extensions to fully incorporate source code into the documentation and to link to externally hosted source code, respectively. They are not trivial to integrate with Hawkmoth, however. Add a dedicated version of linkcode that can be configured with a simple template URI.
This is a bit more convoluted than usual, because we want documentation
built for tagged releases to point at the source code for the release,
and master otherwise. We rely on version having a '.dev0' suffix (or
'.<anything>', really) once we've deviated from the latest release.
The first formatting pass also requires us to wrap {source} and {line}
in extra {}'s.
Added a new commit fixing that, and adjusted signode.line a bit. The references seem more sensible now. |
|
Cool. Looks even better now I guess :) |
Thanks, merged! |
Add
[source]links for documented symbols, similar to what sphinx.ext.viewcode and sphinx.ext.linkcode do.https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html
Running
make htmland looking at examples.html gives the best idea what this does.