When writing new documentation, I find that I’m not always sure of the best way to provide a link to other code/documentation, and I’m hoping we can provide more guidance around this in OEP-19: Developer Documentation.
Questions that I have:
- When/where do I add links to published docs, rather than links to the source documentation?
- Local links can be relative and hopefully will work in both contexts.
- For links across repos, I have been erring on providing links to the source documentation (vs published docs). Can this be a decision?
- When linking to code, what is the best way to provide the link?
- When linking to a specific code example, a github link with
blob/<commit-hash>
and line numbers is ideal. Avoidblob/master
links with page numbers that will break as the file changes. - When linking to docstrings in code, what is the best route?
- Links to
blob/master
with line numbers can easily break as code changes.- This could be misleading if it is broken in non-obvious ways by file changes that change the line numbers.
- It can also be misleading if docs are published for a release and no longer point to links in the release.
- Links to
blob/master
file without line numbers will help find the right file, which could be followed up by a manual search for a class or module-level docstring mentioned in the linking documentation.- This solves the problem of possibly pointing to the wrong lines, but is cumbersome.
- This may still point from named release documentation to master documentation.
- Based on the options I can think of, I think this might be the least evil. It keeps documentation more automatically up-to-date, and hopefully someone will recognize when they have jumped too far into the future.
- Links to
blob/<commit-hash>
with line numbers will provide the correct lines at a point in time, but could easily point to outdated docstrings.- Is there a way to automate flagging/fixing these links?
- Should the link text remind users that the doc may be out of date?
- Other ideas?
- When linking to a specific code example, a github link with
Github introduced the new code navigation features, but I don’t think they have a public API for it (that I could find).