Set up readthedocs in shader-slang.github.io #71
Conversation
This commit adds files required to build a readthedocs project from this repo, based on the readthedocs project for SlangPy
|
I have built a preview of the readthedocs site resulting from this change: https://slang-documentation.readthedocs.io/en/latest/ |
aidanfnv
changed the title
aidanfnv
changed the title
There was a problem hiding this comment.
This script is basically performing string replacement for two cases.
It can be simplified in two lines of bash script something like the following.
# Fix href="#../path/to/file#fragment"
sed -i -E 's/href=(["\'])#(\.\.\/[^"\']+?)#([^"\']+?)\1/href=\1\2.html#\3\1/g' external/std-reference/*.html
# Fix href="#../path/to/file"
sed -i -E 's/href=(["\'])#(\.\.\/[^"\'#]+?)\1/href=\1\2.html\1/g' external/std-reference/*.html
I am wondering why we need this type of fix-up in the first place.
Maybe we should make some modifications on how std-reference repo generates the document?
There was a problem hiding this comment.
The stdlib-reference (with my doc writer change) generates the documents and their paths correctly, but readthedocs does not resolve those paths correctly when it builds its html output. I'm not sure why you can't have relative paths and fragments at the same time, but when readthedocs cannot resolve a path like that, it instead treats the whole path as a fragment.
There was a problem hiding this comment.
Also, I'll simplify that script. Much of the complication was from debugging the link replacement process.
There was a problem hiding this comment.
Well. I wasn't suggesting to use shell script approach.
It was just to double check my understanding...
I think python is fine.
There was a problem hiding this comment.
Oh, sorry, I meant that I'll clean up the python script to remove anything extraneous that I added.
|
I can see some descriptions for each title in the current webpage. I am talking about this, as an example,
|
|
Ah, I should have made my intention clear with that. I was thinking that the links on the current webpage link should be changed to point to the relevant sections of the readthedocs site, and that the new index page should not replace the current webpage. |
This commit changes the sidebar to link to https://shader-slang.org/docs/ instead of index.rst, which is primarily used to populate the sidebar table of contents
Ok. That makes sense. |
|
With the latest commits, the "Standard Modules Reference" link on https://shader-slang.org/docs/ will be changed to the Standard Modules Reference page at https://slang-documentation.readthedocs.io/page/external/stdlib-reference/. RTD redirects page/* paths to the equivalent page in the default language and default RTD branch. I also added a redirect to index.rst, so that navigating to the relatively empty index page will redirect to the current index page at https://shader-slang.org/docs/ However, maybe we do not want those 2 commits right now and instead the links should be changed once all of the docs are included? |
|
Why don't we want to merge the change as soon as possible? |
|
The commit previous to the last replaces our link to the stdlib-reference docs on the main docs page. Technically, it's out of the scope of this PR, and we probably should not relink it to the readthedocs site until they, so I'll revert it. |
2 participants
Fixes #67
This change prepares this repo to be used in a readthedocs project for hosting the Slang Documentation in a single place.
The setup and theming are based on the existing SlangPy readthedocs site (https://slangpy.shader-slang.org/en/latest/), but with the primary difference being that this change also adds 2 Python scripts for post-processing the html build outputs. This post processing is necessary because Sphinx/readthedocs does not assume that relative paths without file extensions should resolve to .html link, and although there is an option to set it up so that it does make that assumption, it will not work with links with anchors.
The debug prints in the script would only be visible in the readthedocs build logs.
Currently the table of contents links to the documents in this repo, as well as the docs in the Slang Standard Module Reference, with other docs like the Slang User Guide to be added in the future. For now, those links go out to the existing docs website on GitHub Pages.