OEP-19: Dev Docs: Guidance when adding links

#1

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. Avoid blob/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?

Github introduced the new code navigation features, but I don’t think they have a public API for it (that I could find).

#2

My goal is that docs are read in their published form. So I would hope that links between docs would link to the published form, not the source form. Published docs can have global links back to their source form (“Edit me on GitHub” or whatever) for the few people that want to switch from being readers to writers.

#3

This is a complicated question. I guess it depends on why you are linking to code.

  • “In order to mumble the frabbitz, use the mumble_frabbitz() function.” This is about a function people can use, not actually about code. This should be a Sphinx (or equivalent) link that can be published as a link to the published documentation for the function.
  • “Back in 2014, we used to write code like this.” I’m not sure how often we write things like this, but this should be a GitHub link, with a commit ID.
  • “Here’s an example of how to write good code.” I wouldn’t make this a link to code elsewhere at all, I would pull the example into the page I was writing.

What are other examples?

#4

I was moving some existing README documentation from edx-platform to edx-drf-extensions. I now realize that some of the details could have moved into docstrings, and that would remove some references.

However, if I do want a README to reference a class somewhere in its directory, how would I link to it? I think I just used a relative path to the file containing the class.

#5

The exact linking technique depends on whether the file is being rendered by Sphinx, and if so, what the autodoc configuration is. A relative path to the file containing the class might render in GitHub, but wouldn’t on ReadTheDocs. It’s not simple.