"git checkout s-l-t/master -- conf.py" is outdated

[bast]

"git checkout s-l-t/master -- conf.py" is outdated

[rkdarst]

Yeah, I guess this doesn't make full sense that conf.py is there. But, since the source directory is the "truth" you point to. The actual content there doesn't have a way to refer to a conf.py file somewhere else (and a quick check doesn't show a way to direct from conf.py to the root, but anyway sphinx-build has to point to the source directory. Even if not ideally organized, I think we should stick to the convention.

[bast]

Also "only index.rst for now" is outdated.

[bast]

It looks to me like conf.py is in the wrong place? I don't think it should be inside "content/", right?

[rkdarst]

It looks to me like conf.py is in the wrong place? I don't think it should be inside "content/", right?

It should be now, the convention is to have it at the root of the content, and I think it somehow uses this to detect stuff. But... I could be wrong, and I don't recall something saying it *has* to be.

[bast]

You are right. But I find this a bit surprising. Since configuration is not "content". But nothing that needs to be changed right now.

[bast]

Do you mind if I move conf.py back to root folder? I find it strange to have it in "content".

[rkdarst]

I don't think so, because:

• sphinx-quickstart, with separate source and build directories, puts conf.py in the sourcedir.
• Default path to find conf.py is same as sourcedir, if it's different then an extra -c option will always be needed, that'll make it less consistent and harder for others to get started
• RTD by default looks for conf.py and uses its directory as source dir: https://docs.readthedocs.io/en/stable/faq.html#where-do-i-need-to-put-my-docs-for-rtd-to-find-it

It may not be content, but content is really "sourcedir" and the standard seems to be to put it in there. I think consistency is more useful (and in the long run less surprising). We could rename "content" to "source" to better match the output of sphinx-quickstart and make it less surprising that way?

[bast]

OK I thought the location of index.rst could be given in conf.py but if that is not easy, I agree we should not require special flags and better leave it where it is.