Why the option build.jobs.post_build in the .readthedocs.yaml doesn't effect the published page?

[zhyantao]

I want to add comments to my Read the Docs.

And I tried adding the sphinx-comments extension (uttrances).

But after my configuration, I can't see the result expected.

While you're browsing zhyantao.github.io > view the source code, you can always find the following source code:

var addUtterances = () => {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src = "https://utteranc.es/client.js";
    script.async = "async";

    script.setAttribute("repo", "zhyantao/zhyantao.github.io");
    script.setAttribute("issue-term", "pathname");
    script.setAttribute("theme", "github-light");
    script.setAttribute("label", "comments");
    script.setAttribute("crossorigin", "anonymous");

    sections = document.querySelectorAll("div.section");  // Need to change div.section to div>section
    if (sections !== null) {
        section = sections[sections.length-1];
        section.appendChild(script);
    }
}
commentsRunWhenDOMLoaded(addUtterances);

Here are some of the key points I think:

• python scripts/fix-comments.py (.readthedocs.yaml)
• fix-comments.py (scripts/fix-comments.py)
• blog page: https://zhyantao.github.io

What I do in the fix-comments.py is just replace div.section to div>section, but that doesn't take effect.

The easiest way I can verify this is by typing the following code on the console:

var addUtterances = () => {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src = "https://utteranc.es/client.js";
    script.async = "async";

    script.setAttribute("repo", "zhyantao/zhyantao.github.io");
    script.setAttribute("issue-term", "pathname");
    script.setAttribute("theme", "github-light");
    script.setAttribute("label", "comments");
    script.setAttribute("crossorigin", "anonymous");

    sections = document.querySelectorAll("div>section"); // modified
    if (sections !== null) {
        section = sections[sections.length-1];
        section.appendChild(script);
    }
}
commentsRunWhenDOMLoaded(addUtterances);

Then, wait a moment, and you'll see it works. I can see comments block in the web page.

[agjohnson]

I believe this is behavior due to a not-yet documented function of our builders.

After the Sphinx build is complete (but before post_build job), the built files are actually copied to a temporary location. It's from this temporary path that the files are then copied to permanent storage. We don't yet surface this path to users however, so any action on build.jobs.post_build will not actually affect the hosted files, just the files on disk.

We haven't decided yet if this path should be static, if the build process should only copy files after the post_build job, or if we'll allow this path to be configurable. Likely either direction, the files shouldn't be copied until after post_build.

So, what you're trying is technically possible, but not yet supported.

[haklc]

I would also greatly benefit from this, certain elements cannot be fixed with JavaScript only.

[humitos]

I found a way to hack this that could be useful as an temporary workaround for now:

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  jobs:
    post_build:
      # This is a small hack to avoid this issue:
      # https://github.com/readthedocs/readthedocs.org/issues/9179
      - cp -r -v public/* ../../artifacts/${READTHEDOCS_VERSION}/sphinx/

Note that in build.jobs.post_build at ../../artifacts/${READTHEDOCS_VERSION}/sphinx/ you will have the output of your sphinx-build command from previous steps. At this job, you can adjust its content as you want before it gets uploaded.

In this particular case, I'm just adding a bunch of extra HTML files that I need.

[sachin-suresh-rapyuta]

@humitos - is there a way to output the list of files under ../../artifacts/${READTHEDOCS_VERSION}/sphinx/?

[humitos]

is there a way to output the list of files under ../../artifacts/${READTHEDOCS_VERSION}/sphinx/?

@sachin-suresh-rapyuta yes, you can do:

build:
  jobs:
    post_builld:
      - find ../../artifacts/${READTHEDOCS_VERSION}/sphinx/

[sachin-suresh-rapyuta]

@humitos, All I need is to download my custom PDF from the bottom left flyer in ReadtheDocs. I tried to get this using the below code, but ended up with the error:

jobs:
    post_build:
      - /home/docs/checkouts/readthedocs.org/user_builds/${READTHEDOCS_PROJECT}/envs/${READTHEDOCS_VERSION}/bin/python -m sphinx -a -E -b simplepdf docs build/simplepdf/en/
      - cp -r -v build/simplepdf/en/* ../../artifacts/${READTHEDOCS_VERSION}/sphinx/

The entire web page of HTML is broken with elements taken from my custom PDF style. Can you please help me with the right command to just copy and download the custom PDF?

[humitos]

@sachin-suresh-rapyuta please, open a new issue explaining what you need and what is not working as expected. It seems your use case is not related to this one

[agjohnson]

I'm going to remove this issue from our roadmap, but we'll address this in #9179 instead. We just need to remove the intermediate path for the build output, and I believe it should be safe at this point.