-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add direct links to github source code to docs #7738
Add direct links to github source code to docs #7738
Conversation
Signed-off-by: John Zielke <j.l.zielke@gmail.com>
Signed-off-by: John Zielke <j.l.zielke@gmail.com>
In response to @KumoLiu and as a general question: I did a quick search on what other repos use this style of source code linking (using this search), and examples include:
I mainly styled the link to github as a github icon to differentiate it from the other [source] link (from viewcode). If we use the github link exclusively, it's personal preference IMO. I think that the icon uses up a little less space and makes it clear you are linking to an "external" site, but on the other hand [source] is widely used already. And changing to the icon is a bit hacky (which is also why I think almost no one has bothered doing it so far) since the linkcode extension does not easily support it. |
I think this is an improvement in general, with two things to discuss:
Thanks @johnzielke for this. @zephyrie please a look to see if this makes sense for our documentation, thanks. |
Thanks @ericspod. I agree with both points. Do you know of any people creating offline docs? If we really needed those, we can of course create a Env variable or similar to change what we generate. Regarding the second point, if there is agreement to merge this I'll have a look at some of the mentioned repositories again and see if there are some cases that this function doesn't cover (decorators might be one of those). Another thing I have to check up on is how the mapping to source code positions might be improved by newer python versions. PS: I was considering creating a small pip package (sphinx extension) that does this and would prevent having to copy this into all repos needing this, since it'squite a common use case nowadays. But I'm not sure how the sentiment for an extra dev dependency for something like this would be in light of recent events with xz. |
I don't think people are but some feedback from others would be helpful before making this change.
The example I gave for an incorrect line range wasn't using decorators in the definition, so I suspect there's just something mildly wrong with the algorithm that can be fixed. Perhaps someone else has it in their versions of this plugin so yeah checking around would help. If not we can still merge this since I think it's an improvement over the reformatted code.
This would be a dependency of the sphinx environment and not for MONAI so much less impactful. If it's something other people would want it could be a good project to start. New dependencies and libraries are unavoidable so one famous example of an attempted exploit shouldn't put us off. We should be cautious and have some way of verifying contributions, but that's a community-wide issue. |
Signed-off-by: John Zielke <j.l.zielke@gmail.com>
I haven't seen any demand for offline documentation, so removing the viewcode extension seems reasonable, and any minor errors in mapping line ranges can be addressed. And I think linking directly to GitHub source code is a great idea and it offers a better user experience overall! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this looks good now and the links go to the right places for me. Thanks all!
/build |
@KumoLiu On https://docs.monai.io/en/latest/metrics.html I am now not seeing any more links to source anymore on "latest". Is this normal or is there some error in the build? I was unable to find the CI job deploying the pages. |
here is the job link: https://github.com/Project-MONAI/MONAI/actions/runs/9069259715/job/24918422082 |
I think the issue is with read the docs. See #7779 |
Description
This adds direct links to the respective source code of classes, methods, etc. to the docs.
In my opinion these nicer and more useful than viewing the source code in copy in the docs.
I currently added it in addition to the links to the source files copied into the docs. If desired this could also be done instead of.
I also used a github logo instead of another
[source]
link.I am not sure whether there is any easier way to change that into the logo than the way I have done, but this one seems to work.
Types of changes
./runtests.sh -f -u --net --coverage
../runtests.sh --quick --unittests --disttests
.make html
command in thedocs/
folder.