Repository: readthedocs/readthedocs.org

Issue:
MkDocs: artifacts are not found when YAML file is not on root directory
## Details

* Read the Docs project URL: https://readthedocs.org/projects/civicactions-handbook/
* Read the Docs username (if applicable): https://readthedocs.org/profiles/dmundra/

## Expected Result

*A description of what you wanted to happen*

We expect that pull request sites are loaded and the changes merged to the main branch are loaded on the site as well.

## Actual Result

*A description of what actually happened*

For the first issue, here is the latest pull request example: https://github.com/CivicActions/guidebook/pull/1033. We reset the rtd token as well but that didn't matter. The build passes https://readthedocs.org/projects/civicactions-handbook/builds/19264729/ but no site has been created.

The second issue most recently https://readthedocs.org/projects/civicactions-handbook/builds/19264408/ we published some changes, but those changes do not appear on the live site https://guidebook.civicactions.com/en/latest/about-civicactions/diversity-equity-inclusion/resources/

Any recommendations for troubleshooting?



Discussion:
> For the first issue, here is the latest pull request example: [CivicActions/guidebook#1033](https://github.com/CivicActions/guidebook/pull/1033). We reset the rtd token as well but that didn't matter. The build passes [readthedocs.org/projects/civicactions-handbook/builds/19264729](https://readthedocs.org/projects/civicactions-handbook/builds/19264729/) but no site has been created.

This looks like a temporal issue, I'd say. I just opened a testing pr at https://github.com/readthedocs/test-builds/pull/2095, triggered this build https://readthedocs.org/projects/test-builds/builds/19267182/ and generated this documentation https://test-builds--2095.org.readthedocs.build/en/2095/

Can you please take a look at the suggestion from https://docs.readthedocs.io/en/latest/pull-requests.html#troubleshooting just in case?



> The second issue most recently [readthedocs.org/projects/civicactions-handbook/builds/19264408](https://readthedocs.org/projects/civicactions-handbook/builds/19264408/) we published some changes, but those changes do not appear on the live site [guidebook.civicactions.com/en/latest/about-civicactions/diversity-equity-inclusion/resources](https://guidebook.civicactions.com/en/latest/about-civicactions/diversity-equity-inclusion/resources/)

What are the differences we should be checking for? Can you point us at specific page where the updated content should be there and it's not?
Thanks for the response. Yes, we tried the troubleshooting steps and I a triggered a build this morning to confirm if it was temporal issue but the builds are not progressing passed the triggered state (for both latest and the pull request), builds:

- https://readthedocs.org/projects/civicactions-handbook/builds/19271175/
- https://readthedocs.org/projects/civicactions-handbook/builds/19271225/

> What are the differences we should be checking for? Can you point us at specific page where the updated content should be there and it's not?

Ya, we are looking for changes from this commit https://github.com/CivicActions/guidebook/commit/a614e7b1aaa30a9016c66cd7e4238338ffcc1451 to appear on this page https://guidebook.civicactions.com/en/latest/about-civicactions/diversity-equity-inclusion/resources/. For example we should see 'Code of conduct' text and we don't.
Here is another pull request https://github.com/CivicActions/guidebook/pull/1034 that generated a build but the site doesn't appear https://civicactions-handbook--1034.org.readthedocs.build/en/1034/
@dmundra thanks for providing feedback here!

We're investigating a possible regression related to your use of a custom MkDocs configuration path `.config/mkdocs.yml`, it seems that it has affected something after a recent change to builders. We'll get back with more info :+1: 
Thanks @benjaoming for the update.

Resolving patch:
diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -295,10 +295,19 @@ def build(self):
             '-m',
             'mkdocs',
             self.builder,
-            '--clean',
-            '--site-dir',
-            self.build_dir,
-            '--config-file',
+            "--clean",
+            # ``site_dir`` is relative to where the mkdocs.yaml file is
+            # https://www.mkdocs.org/user-guide/configuration/#site_dir
+            # Example:
+            #
+            #  when ``--config-file=docs/mkdocs.yml``,
+            # it must be ``--site-dir=../_readthedocs/html``
+            "--site-dir",
+            os.path.join(
+                os.path.relpath(self.project_path, os.path.dirname(self.yaml_file)),
+                self.build_dir,
+            ),
+            "--config-file",
             os.path.relpath(self.yaml_file, self.project_path),
         ]
         if self.config.mkdocs.fail_on_warning:


Test patch:
diff --git a/readthedocs/projects/tests/test_build_tasks.py b/readthedocs/projects/tests/test_build_tasks.py
--- a/readthedocs/projects/tests/test_build_tasks.py
+++ b/readthedocs/projects/tests/test_build_tasks.py
@@ -1257,7 +1257,7 @@ def test_mkdocs_fail_on_warning(self, load_yaml_config):
                     "build",
                     "--clean",
                     "--site-dir",
-                    "_readthedocs/html",
+                    "../_readthedocs/html",
                     "--config-file",
                     "docs/mkdocs.yaml",
                     "--strict",  # fail on warning flag