Fix links to source code in documentation pages #1444
Conversation
Use the current tag for `"github_version"` while configuring Sphinx. This way, the links pointing to the source code of each function, class or method points to the actual code corresponding to that version, and not always to the code in `main`.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1444 +/- ##
=======================================
Coverage 82.33% 82.33%
=======================================
Files 171 171
Lines 26019 26019
=======================================
Hits 21423 21423
Misses 4596 4596 ☔ View full report in Codecov by Sentry. |
|
I'm going to hard code the |
|
OH... I think i know what you're running into. Look at this line from the build: https://dev.azure.com/simpeg/simpeg/_build/results?buildId=4022&view=logs&j=a3da1655-dbd3-5466-5850-e4f85983e337&t=b6fcda75-f2ce-5ec9-7c70-5cf16be9995c&l=45 The sources that CI pulls don't include tags, so it won't get an accurate version number when it's installed. You should be able to configure the checkout step to pull tags https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines |
|
Nice catch! Thanks for noticing it! Fetching tags is also super relevant for #1428. |
Sync tags in testing jobs, so the documentation builds as part of the test suits is done against the correct tag. This also fix the issue of the built artifact not being correct.
This commit should be reverted.
|
I'm trying to dig more into the issue with tags. Checking out the repo with tags works (https://dev.azure.com/simpeg/simpeg/_build/results?buildId=4027&view=logs&jobId=50e2b49d-b8ca-5aaf-b730-aab43fbdd612&j=e13373ee-b201-51bd-a7eb-56842f187dd4&t=d8226405-3c7c-58b3-ab29-76fc135fa198), but the simpeg version is not correctly set (https://dev.azure.com/simpeg/simpeg/_build/results?buildId=4027&view=logs&jobId=50e2b49d-b8ca-5aaf-b730-aab43fbdd612&j=e13373ee-b201-51bd-a7eb-56842f187dd4&t=9de72094-40d6-5eb3-386e-721ab4adb7b6). BTW, apparently I'm still used to type SimPEG haha. Need to retrain muscle memory. |
|
Great. Another thing is that in the testing scripts it does directly modify a tracked file (It appends a python version to the In doesn't do this currently on main when building the documentation for release and documentation builds though which is why the version is correct there. |
Apply my own suggestions from the comment
Apply my own suggestions from the comment
Restore the previous configuration for `html_context`: it configures only the links to edit files, not to the source code of classes, functions and methods.
|
Ok, I totally misundertood the documentation of pytest theme (https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html). The changes to the Those links are configured through the |
|
Now the source links are working properly!
That link won't work because the doc pages with I'm removing the hardcoded tag, and after that I think this should be ready! |
santisoler
changed the title
|
@jcapriot, I've been seeing that the Might it be related to the the fact that I disabled the shallow depth while checking out the repo? |
|
It's possible it's some race condition happening with the multiprocessing tests. There are some broken pipe messages in those tests when they pass it looks like. |
|
Right! Nice catch. I'll wait for #1464 to fix it then. |
|
I hope that fixes it, (it at least fixes the broken pipe messages). |
|
Well 💩, looks like it’s still racing away. |
Revert this commit before merging.
|
I've just disabled pytest's capture of stdout and stderr so we can get more idea of what's going on... let's wait to see if there is some information in those messages. |
|
Not sure why but on this branch, the mappings for the dask meta aren't being sent to the correct workers: Whereas on main they are: https://dev.azure.com/simpeg/simpeg/_build/results?buildId=4141&view=logs&j=894b861d-556c-5901-7578-c933b75ce341&t=ed1e0f4a-533f-5064-832c-7c51df369f6b&l=548 |
I can reproduce this locally on my machine, give me a minute to do some debugging. |
Matches change in simpeg#1444
|
Took me a bit, but #1469 should fix the race condition. |
|
Merging this now that CI passes! Thanks @jcapriot! |
Summary
Update the
linkcode_resolvefunction in Sphinx configuration file so the links to the source code of each function, class or method points to the actual code corresponding to that version, and not always to the code inmain. Update some Azure configurations: checkout simpeg repo without shallow depth and fetching tags. Clean up the working directory before installing SimPEG so the version doesn't have an extra hash.PR Checklist
expect style.
to a Pull Request
@simpeg/simpeg-developerswhen ready for review.Reference issue
What does this implement/fix?
This PR fixes a current issue in SimPEG docs: links to source code lead to the current code in the
mainbranch, which is not the code that corresponds to the documentation. This inconsistency could lead to confusion among users: it will lead them to think they are running the code they are reading while they are not.Additional information
TODO: