Added pull request build

[Tom-van-Woudenberg]

No description provided.

[Tom-van-Woudenberg]

Adds documentation to manual: https://teachbooks.io/manual/pull_request_BTD/features/pull_request_build.html

Replaces extension of deploy-book-workflow: TeachBooks/deploy-book-workflow#73

@moorepants, indeed easy to set up!

@rlanzafame, fancy reviewing this?

Afterwards, it deserves a post on the website.

[moorepants]

Nice!

[rlanzafame]

Looks good! A few comments/questions though:

1. Can you provide a set of example links to illustrate? If you give me links I can update text. I presume given the screenshot you have it set up for the Manual? I have no way to find it and I gave up trying to guess the link.
2. I added RTD to my account but can't see anything related to TeachBooks...do you still need to add me to the RTD Project for the Manual?
3. Why can't we use the APA extension? It looks like the problem could be that you use jupyter book to build the book instead of teachbooks, which handles the manual file transfer. I can change it, but then I did not see the config.py file that is needed for the config sphinx part...is that in RTD? Is that why we can't use the APA thing?
4. The first paragraph made me realize we need to add a bit more "meat" to the Git explanation to include PR and fork descriptions improve git chapter, specifically forks and PR's #103

[Tom-van-Woudenberg]

Looks good! A few comments/questions though:

1. Can you provide a set of example links to illustrate? If you give me links I can update text. I presume given the screenshot you have it set up for the Manual? I have no way to find it and I gave up trying to guess the link.

I couldn't set it up for the manual because it has those local extensions. I think the conversion from _config.yml to conf.py doesn't support local extensions (although I could be mistaken).

Another example is here: CIEM5000-2025/book#5. But maybe it would be better to have a dedicated example book in teachbook org which allows people to fork to test it themselves too.

2. I added RTD to my account but can't see anything related to TeachBooks...do you still need to add me to the RTD Project for the Manual?

So the project doesn't exist and yes I need to add you manually in RTD if it would exist.

3. Why can't we use the APA extension? It looks like the problem could be that you use jupyter book to build the book instead of teachbooks, which handles the manual file transfer. I can change it, but then I did not see the config.py file that is needed for the config sphinx part...is that in RTD? Is that why we can't use the APA thing?

Is teavhbooks required for the applications in _ext? I don't use jupyter book to build the book, just to make the conf.py file. After that, RTD uses it's sphinx option to build the book

[rlanzafame]

1. I still don't know how to find the RTD pages for the book that you sent.
2. Yes, good idea to set up something that can be forked - maybe you can set up something that would be useful for a teacher and i can be the tester? github.com/teachbooks/rtd-example?
3. Ahhh so you convert your book to a sphinx book and RTD does the rest. It's like the reverse process of Jason's book, cool. It is definitely possible to use the APA thing with RTD then; the question is whether I need to add a small change to the teachbooks package to help facilitate it. Maybe I can try this out on the test book.

[moorepants]

For every primary book repository, the owner of that repository would have to connect it to read the docs and set the setting in read the docs to "build previews on pull requests". You'd have to have to have a RTD configuration file also, so that all the teachbooks tooling is available for the RTD builds. After all that, when anyone opens a PR on the primary repository, it should show the preview build in the CI check list (when green check you can click and open the preview website).

[Tom-van-Woudenberg]

1. I still don't know how to find the RTD pages for the book that you sent.

Here: , leading to https://ciem5000--5.org.readthedocs.build/5/intro.html

2. Yes, good idea to set up something that can be forked - maybe you can set up something that would be useful for a teacher and i can be the tester? github.com/teachbooks/rtd-example?

Done: https://github.com/TeachBooks/Read-the-Docs-example-book, including reference to it in this branch

3. Ahhh so you convert your book to a sphinx book and RTD does the rest. It's like the reverse process of Jason's book, cool. It is definitely possible to use the APA thing with RTD then; the question is whether I need to add a small change to the teachbooks package to help facilitate it. Maybe I can try this out on the test book.

Teachbooks is not used with read-the-docs and I doubt it whether it's possible to do so. You could run the 'process only' option of TeachBooks as a 'pre-build' step thought. I think the problem is that jupyter-book config sphinx book/ doensn't convert the local_extensions part of the config, but I'm not sure.

[Tom-van-Woudenberg]

For every primary book repository, the owner of that repository would have to connect it to read the docs and set the setting in read the docs to "build previews on pull requests". You'd have to have to have a RTD configuration file also, so that all the teachbooks tooling is available for the RTD builds. After all that, when anyone opens a PR on the primary repository, it should show the preview build in the CI check list (when green check you can click and open the preview website).

Yes, this is all explained on this page in the manual :)

[rlanzafame]

OK I think that wraps it up for now. the last text changes describes how we haven't checked the APA/local extensions thing but that it should be possible. I set it up as an issue for later TeachBooks/Read-the-Docs-example-book#3

[rlanzafame]

Hey @Tom-van-Woudenberg I'm done! I'll leave the final button-pushing to you in case you want to read the additions I made one more time

[Tom-van-Woudenberg]

@rlanzafame , this part is not finished, what do you mean?

[Tom-van-Woudenberg]

After this you can merge!