Open humitos opened 2 years ago
It will be super-useful to have a list of <Section title>: <URL>
Also to handle the special case: No changes in docs. Most PRs (unfortunately) don't contain documentation changes. This will be interesting to explore in the future. If, however, there is automated API docs, we might have a situation where almost all PRs generate really cool and meaningful links.
It will be super-useful to have a list of
<Section title>: <URL>
Getting the title correctly may be a little harder to do. However, I'd assume we can get the h1
from each of the modified files/pages and use that. However, this "technique" won't work for doctools like Docsify ๐
Also to handle the special case: No changes in docs. Most PRs (unfortunately) don't contain documentation changes. This will be interesting to explore in the future. If, however, there is automated API docs, we might have a situation where almost all PRs generate really cool and meaningful links.
I'm not sure to follow this. Can you expand this and give an explicit example of how it would work, please?
I'm not sure to follow this. Can you expand this and give an explicit example of how it would work, please?
So these are more scenarios of what can happen with the list:
User modified or added a .md or .rst file: We create a nice little list corresponding to the pages that have been changed such that the user may click directly to the section of the docs that were modified/added.
We have built the docs again but actually we don't have any changes to list? Perhaps no files were edited and the documentation is completely unchanged, so we shouldn't "disturb" the PR reader with links? Perhaps a configuration file was edited but nothing detectable changed? Perhaps the footer was changed and everything is updated?
We detect that all pages have changed, perhaps because we correctly see that the footer or configuration or navigation structure is affected.
Nothing in the documentation pages have changed, but the automatically generated API docs have changes.
@benjaoming it seems you are describing exactly what we have discussed already in https://github.com/readthedocs/readthedocs.org/issues/8545
This problem is pretty complex to solve correctly for all the users under all these scenarios and that's why we haven't built it yet. Due to its complexity, I do not want to solve this problem on this simple action itself. I think it would be enough for most cases if we can just put the links for all the pages matching documentation files modified in the PR.
People will always have the link to the index itself in case they want to dig more on the other pages that may have been modified because of a code change, for example.
Just noting that:
@humitos I believe that conditional builds are different from this issue because here, we are trying to detect the changes post-build while #8545 tries to detect changes pre-build.
@benjaoming
we are trying to detect the changes post-build while #8545 tries to detect changes pre-build.
This is not exactly how the GitHub Action works now, tho. We could execute the action only after the build has finished and succeeded. However, in that case, I'm not sure what extra information will we have available in that case currently: there is no API that exposes what files have changed in the documentation output or similar. How are you thinking that post-build will give us more useful data here?
Sorry I should have presented that (wrong) assumption earlier. In this case, it's much more like #8545. I like the idea of solving these two issues at the same time, both predicting when to build and what URLs will change. There's a lot of developers'+server time to be won if we can get our predictions right in >90% of cases.
Hi hi! This would be useful for Python PEPs repository as well as the Python devguide, where this would make the reviewer process easier by eliminating the need to navigate to the specific PEP/page that has been modified in the PR!
If this is something where all the information needed to detemine the relevant URL is already available (or something you'd be OK having explicit configuration for), that would be useful to know since someone (maybe me) from the community could contribute the logic change for that. :)
@pradyunsg
If this is something where all the information needed to detemine the relevant URL is already available (or something you'd be OK having explicit configuration for)
Some of the relevant information is present, but some of it has to be explicitly defined by the user setting up the GHA I'd say. GHA provides the files that were modified in the repository (e.g. using github.rest.pulls.listFiles
inside the action) but we will need to know "what's the logic to convert that file into a URL".
That logic will depend on the doctool used (MkDocs, Sphinx, Docusaurus, etc) and also on the options specified in the doctool itself (e.g. "pretty URL" --ending with .html
or not). I think we can have these logics hardcoded in the GHA itself and ask the user for the missing pieces of configurations so we can effectively generate the URL based on the filename. It may not work for all the cases, but covering the most common ones would probably be enough for the first version ๐
I don't think I will have the time to prioritize this work sooner, but I'd be happy to help with reviews ๐ง and directions โคด๏ธ if someone wants to jump into this.
We start talking about a potential implementation for this feature at https://github.com/readthedocs/readthedocs.org/pull/11507/. I'd love to have your feedback.
We could detect there were changes to specific files (via #3) and insert direct links to those documentation pages as well. For example, if the file
docs/page/section.rst
was modified, we could insert the linkhttps://readthedocs-preview--1.org.readthedocs.build/en/1/pages/section.html
There are some notes to mention:
docs/
from the filename)/pages/section/
or/pages/section.html
)