Problem with MkDocs and Read The Docs

[ghost]

i cant use mkdocs .
Error :
`ERROR - Config value: 'site_dir'. Error: The 'site_dir' should not be within the 'docs_dir' as this leads to the build directory being copied into itself and duplicate nested files in the 'site_dir'.(site_dir: '/home/docs/checkouts/readthedocs.org/user_builds/zkit-framework/checkouts/latest/_build/html', docs_dir: '/home/docs/checkouts/readthedocs.org/user_builds/zkit-framework/checkouts/latest')

Aborted with 1 Configuration Errors!
`
What should i do ? i do best with markdown . but need MkDocs on readthedocs . all others projects have this problem too . (it works using sphinx) . is this probelm from Mkdocs or ReadtheDocs ???

[lavahot]

So, do you see how your site_dir is a subdirectory of your docs_dir? you need to change your site_dir to someplace else. That's all this error is complaining about.

[timvink]

This error is related to your project directory structure. See https://www.mkdocs.org/#getting-started for the correct structure.

It seems you've also configured the site_dir option for your theme. This is where the output of your build is, and you need to make sure it's in another directory then where your source files are (the docs/ folder). See https://www.mkdocs.org/user-guide/configuration/#site_dir

[ghost]

i didnt do anthing . it was all automic . its done from the 'Read the Docs.org' .

[ghost]

if it was my configuration i would do sth . but not . i cant do anything .

[facelessuser]

MkDocs doesn't directly provide anything to 'Read the Docs.org'. If you have an issue with what they are doing, you'll have to take it up with them.

The people who are trying to help are giving valid relevant information. Those are the relevant settings that MkDocs provides. Any other service that prevents you from setting those, or augments them those, will need to have this issue taken up with them.

[lavahot]

@000Zer000 Would you like to post your configuration?

[ghost]

What should i post ?? . a picture from 'None' . i didnt do any configuration.

[martinbira]

So if you've followed the instructions on https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html on how to get started using ReadTheDocs with MkDocs and there are issues with the basic configuration, that seems like it's an issue that should be adressed with ReadTheDocs and not MkDocs.

[ghost]

So Im closing it

[Zylann]

I'm having the same problem, and here are the details. (Scroll down for workaround)

My repo has the following structure:

.readthedocs
addons/
	zylann.hterrain/
		doc/
			mkdocs.yml
			docs/
				index.md

As far as MkDocs is concerned, for everything under doc/, the directory structure should be respected with proper defaults. What's above it is RTD's business, I assume. My docs source files are under docs/ next to my project file, which is what docs_dir defaults to, so nowhere should I have to specify docs_dir, right?

Now RTD is running the following command:

/home/docs/checkouts/readthedocs.org/user_builds/hterrain-plugin/envs/latest/bin/python -m mkdocs build --clean --site-dir _build/html --config-file addons/zylann.hterrain/doc/mkdocs.yml

Which causes the error The 'site_dir' should not be within the 'docs_dir', because according to MkDocs, one of the following paths is contained within the other:

site_dir: /home/docs/checkouts/readthedocs.org/user_builds/hterrain-plugin/checkouts/latest/addons/zylann.hterrain/doc/_build/html
docs_dir: /home/docs/checkouts/readthedocs.org/user_builds/hterrain-plugin/checkouts/latest

As you can see, for site_dir, MkDocs concatenated 3 things:

• The working directory (/home/docs/checkouts/readthedocs.org/user_builds/hterrain-plugin/checkouts/latest/)
• The directory under which mkdocs.yml is (addons/zylann.hterrain/doc). This was not specified explicitely by RTD so I assume MkDocs guessed it from --config-file?
• The path specified by RTD's command line (_build/html)

But for docs_dir, MkDocs defaulted to the working directory, and not the docs/ directory right next to where mkdocs.yml is. The doc says it should defaults to docs. Why didn't it guess the same way as for site_dir? Is that behavior expected?
If yes, how do I tell MkDocs to use my docs dir, despite the fact it's already relatively using the correct file structure? Should it still be solved on RTD side or MkDocs side?

Build: https://readthedocs.org/projects/hterrain-plugin/builds/12444374/

---

Update: the build succeeds if I add this to mkdocs.yml:

docs_dir: docs

Which is again what docs_dir is supposed to default to (https://www.mkdocs.org/user-guide/configuration/#docs_dir)
So to me that looks like a bug.

[waylan]

Which is again what docs_dir is supposed to default to (https://www.mkdocs.org/user-guide/configuration/#docs_dir)
So to me that looks like a bug.

If this is a bug, then it is a bug with ReadTheDocs, not MkDocs. ReadTheDocs' source code can be found at readthedocs/readthedocs.org. They don't let MkDocs load its own config. Instead they load it themselves, update various config items with their own defaults, and then pass it to MkDocs.

The issue you are having is with the second step. Because you have not defined a value, they assign their default (not our default). And because you are not using ReadTheDocs default file structure, their default is failing. But when you define your own value, they don't force their default and it works fine.

@Zylann, If you want to address this issue, you need to take this to ReadTheDocs. It is out of our hands.