mkdocs.yml not read when in docs dir

[blairconrad]

Details

• Project URL: https://github.com/FakeItEasy/FakeItEasy
• Build URL (if applicable): http://fakeiteasy.readthedocs.io/en/4.2.0/
• Read the Docs username (if applicable): blairconrad

Expected Result

The table of contents in the mkdocs.yml file is not respected, and our code formatting lost its "GitHub" styling. It's as if the mkdocs.yml file is not read at all.
A description of what actually happened

The Build Process documentation says:

When you choose Mkdocs as your Documentation Type, we will first look for a mkdocs.yml file in your repository. If we don’t find one, we will generate one for you. We will look inside a doc or docs directory first, and then default to the top-level of your documentation.

As part of FakeItEasy/FakeItEasy#1250, we moved our mkdocs.yml file from the root of the repo to the docs directory. We expected no changes to the generated docs.

Actual Result

Thereafter, the docs for the 4.2.0 release

1. no longer used GitHub style rendering for the code, and
2. did not respect the Table of Contents in the mkdocs.yml.

It's as if the mkdocs.yml file was not read at all.

I thought the problem might've been a bad docs_dir, so I added these lines to the YML:

docs_dir: .
site_dir: ../artifacts/docs

But it made no difference.
For now, I'm working around the problem by moving the mkdocs.yml file back to the root, as seen in FakeItEasy/FakeItEasy#1267.

[stsewd]

@blairconrad are you still having this issue?

[blairconrad]

@stsewd, I am. I just pushed updates to, and triggered a build of, https://bfakeiteasy.readthedocs.io/en/fix-docs/.
You can see the table of contents is just an alphabetical list of pages, with no ordering or hierarchy, and the code formatting, for example in https://bfakeiteasy.readthedocs.io/en/fix-docs/argument-constraints/, is not GitHub-styled.

Compare mkdocs.yml in the docs directory on the left, and mkdocs.yml at the project root on the right:

[stsewd]

Thanks for the screenshot, looks like rtd isn't searching for the mkdocs.yml file in other directories, just in the root

https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L60-L60

Just a question, there is any difference putting it in another directory? Or it is just for keeping the root clean?

This will be allowed with the new configuration file https://github.com/rtfd/readthedocs.org/pull/4084/files#diff-bd10ec86a98c7d6bdf7ea8455b8fdfd4R78

[blairconrad]

Oh, it was for keeping the root clean and because the docs actually said that doc or docs were the preferred locations.

Thanks, I'll keep an eye on #4084.

[stsewd]

I had tested the new changes with your project, you may want to see this https://www.mkdocs.org/about/release-notes/#stricter-directory-validation

[stsewd]

So, with the information above, we don't want to support that behavior (is deprecated and marked as an error in recent versions). What we will support (yaml file only) is having a mkdocs project inside another directory:

• mkdocs/docs/index.md
• mkdocs/mkdocs.yml

[blairconrad]

you may want to see this mkdocs.org/about/release-notes/#stricter-directory-validation

Yup, very clear, @stsewd. At least we know what not to do now.

Although I'm confused by

• mkdocs/docs/index.md
• mkdocs/docs/mkdocs.yml

I'd've expected

• mkdocs/docs/index.md
• mkdocs/mkdocs.yml

What do I miss?

[stsewd]

Ups, my mistake. It is as you mention (editing my comment)