Do you use the view source feature in the documentation?

Django Internals
1

Hello hello :wave:

In the documentation we have some links to view the source code.
We have a module directory here: Overview: module code | Django documentation | Django
We also have some links between class/function definitions and the source code, here is an example: Django Utils | Django documentation | Django

You may not have noticed because it doesn’t cover all of our docs (there is a ticket about it :+1: ).

My question is:

  • Do you use this?
  • If this was everywhere, can you see yourself using this?

Personally, I can’t see myself getting new value from this.

I trust in the quality of the docs and that they are up-to-date (otherwise this would be useful).
I also trust that the docs have been crafted to tell me what I need to know rather than everything.

But I also know how to check the source code if I was curious.

That’s just me, would love to know what you all think :smiling_face:

2

Do you use the view source feature in the documentation?

For me this currently mostly a no. My typical django source lookup is either navigating to the github repo for quick lookups, or spinning up the IDE with django trunk, if I want to get the bigger picture. (While the IDE is more helpful to navigate across modules and inheritance chains with its superior symbol tracking, github is typically faster to access for me.)

We have a module directory here: Overview: module code | Django documentation | Django

I stumbled over the listing several times from search engines results, but found it not so helpful due missing most of the deal.

We also have some links between class/function definitions and the source code, here is an example: Django Utils | Django documentation | Django

I’d love to see more of these docs ↔ code interlinking, as I find it very helpful to be able to jump to the code (module). For example - for some time now the python module docs have a similar feature with a link at the top pointing to the module in the source tree. This already saved me a lot of time navigating to the modules by hand, which gets complicated by the fact, that the python repo is a mixture of different languages with a not so obvious folder structure for casual bypassers like me. The repo structure of django is much more straight forward to grasp as python dev, so def. not as bad to navigate it myself.

Now to the issues I see with the current docs ↔ code linkage - django is more on the heavy inheritance side of things, so it is often needed to follow the inheritance chain up- or downwards to get to the actual implementation. Since this is currently not possible from the docs sources, it turns the source navigation attempt into a dead end. Idk if that would be fixable with a reasonable effort (link directly into github realms like python does?), I kinda have the same issue with embedded source in my Sphinx driven docs and did not bother yet to look into it.

So while I’d love to see more docs ↔ code links, I dont know if it is worth the trouble to get it running with better source navigation.

1 Like
3

link directly into github realms

Interesting idea.

I came across this example. Sarah – I’m not sure if this method gets around the need to have a working django project :thinking:

4

Oh wow, thats a really sophisticated version, even with proper line highlighting :heart_eyes:

My first first guess is, that

...
mod = importlib.import_module(info["module"])
...

will create havoc without proper project bootstrapping. But this prolly still wont get all modules properly covered due to the sheer mass of configuration options pointing into different places/files.

I have not dealt with sphinx extensions myself for a while, but I wonder if a lighter solution would be possible by grabbing the line offsets from the parsing sphinx already does. Done on a certain commit, the line offsets should be valid to construct github permalinks with line highlighting. Well just brainstorming atm…

5

@jerch thank you for your input :star:

I’m not sure if this method gets around the need to have a working django project :thinking:

@smithdc1 It’s similar to the sphinx extension in that it tries to import the module, which then triggers any code that is run on import, so we would have the same problem unfortunately.

We also have a PR for the Github links which looks mature: Fixes #392 -- Enable Sphinx extension and update source links by zachborboa · Pull Request #16203 · django/django · GitHub

6

Oh sorry for cluttering the thread, wasn’t aware of that PR. So this got already covered :slight_smile:

7

No, on the contrary! I only looked up the GitHub links due to this thread, so thank you don’t be sorry :heart:

For context, I want to confirm if this linking is wanted as it’s not trivial to fix and one option is just to remove it :sweat_smile:

Currently I’m concluding that it is wanted and we want it linked to GitHub.
I will wait a few more days in case anyone else wants to share their opinions on this.

8

Hi Sarah,

I have used it sporadically; it is nice to double check the behaviour is as documented. When I need to refer to the code however I use GitHub because it’s the source of truth and I can copy links directly to lines in the code etc. If the docs could link to the relevant tagged version on GitHub that’s be awesome.

David.

1 Like
9

Just to chime in, I have also found this useful at times, and would also prefer that it just link to the GitHub repository.

2 Likes
10

Sometimes. There are situations where it’s handy to have - usually when I’m sitting with someone esle and it’s the easiest way to get to the code.

I do agree with the previous comments that if it were linked to the respective sources in github that it would be more useful. But I don’t see myself relying upon it on a regular basis. I’m not sure it’s worth any degree of significant effort to implement or maintain, if it can’t be done so relatively automatically.

1 Like
11

Can I just +1 the links to GitHub comments. Often enough I’d go from the docs to my local checkout to GitHub, in order to grab a permalink to post in a ticket or PR comment. If we could go straight to GitHub that would save a step at least sometimes.

3 Likes
12

While I’ve had some use for the documentation, an issue I feel like I’ve encountered several times is that search engines bring me to the source page, even though I was searching for the docs. So at times they’ve been slightly counterproductive!