sphinx-build: Can't find conf.py in dir given by -c (v7.2.6)

[Emil Karlén]

Hello!

I want the Sphinx source root to be the root directory of the project, but have Sphinx conf.py in a subdirectory "sphinx".

The Sphinx Makefile is in the project root dir, and I have added arguments

  -c sphinx

to the Makefile.

But when I try to build Sphinx says that it cannot find conf.py, and also that it looks for it in the directory sphinx/<BUILD-TARGET>:

$ make html
Running Sphinx v7.2.6

Configuration error:
config directory doesn't contain a conf.py file (/home/emil/pgm/tools/sphinx/test-prj/sphinx/html)
make: *** [Makefile:20: html] Fel 2
$ make text
Running Sphinx v7.2.6

Configuration error:
config directory doesn't contain a conf.py file (/home/emil/pgm/tools/sphinx/test-prj/sphinx/text)
make: *** [Makefile:20: text] Fel 2

Here is my Makefile:

SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = build

help:
       @$(SPHINXBUILD) -M help -c sphinx "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

%: Makefile
       @$(SPHINXBUILD) -M $@ -c sphinx "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Thankful for help, Emil

[Steevie]

On Fri, 15 Mar 2024 17:54:25 -0700 (PDT), Emil Karlén wrote:

> Hello!
>
> I want the Sphinx source root to be the root directory of the project,
> but have Sphinx conf.py in a subdirectory "sphinx".
> The Sphinx Makefile is in the project root dir, and I have added
> arguments
> -c sphinx
> to the Makefile.

It should be -C sphinx, with capital "C"

HTH,
Stefano

[Emil Karlén]

Hi, thanks for help,

but the sphinx-build man page says it should be a lower case "-c":

       -c path
              Don't  look for the conf.py in the source directory, but use the
              given configuration directory instead.  Note that various  other
              files and paths given by configuration values are expected to be
              relative to the configuration directory, so they will have to be
              present at this location too.

              New in version 0.3.

       -C     Don't  look  for a configuration file; only take options via the
              -D option.

              New in version 0.5.

I tried with capital "-C" but that doesn't work :(

/Emil

[Matthias Geier]

Hi Emil.

The lowercase "-c" is fine, but the problem is that the usage of "-M"
is brittle.

See https://www.sphinx-doc.org/en/master/man/sphinx-build.html#make-mode,
which mentions:

"""
Sphinx only recognizes the -M option if it is used first, along with
the source and output directories, before any other options are
passed.
"""

See also https://github.com/sphinx-doc/sphinx/issues/6603.

So if you move your "-c" argument after "$(BUILDDIR)", it should work.

I think the "-M" option is very confusing (which is why I still prefer
not using it and selecting the builder with "-b"), and obviously the
error message is not at all helpful, and I hope this will be improved
in the future.
Also, it is still not even mentioned in the "--help" output.

There have been a plethora of issues and PRs about this in the past,
this is a short selection:

https://github.com/sphinx-doc/sphinx/issues/3196
https://github.com/sphinx-doc/sphinx/pull/4320
https://github.com/sphinx-doc/sphinx/issues/5618
https://github.com/sphinx-doc/sphinx/pull/6938
https://github.com/sphinx-doc/sphinx/pull/6939
https://github.com/sphinx-doc/sphinx/issues/11656

cheers,
Matthias

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/3cafe9ec-c2ad-4413-a46b-db90b6532b56n%40googlegroups.com.

[Steevie]

On Fri, 29 Mar 2024 06:44:20 -0700 (PDT), Emil Karlén wrote:

> Hi, thanks for help,
>
> but the sphinx-build man page says it should be a lower case "-c":

The "-C" option I was referring to is an option of make, not of sphinx-
build. I didn't notice that you did add it to the makefile, sorry for the
confusion.

Cheers,
Stefano

[Emil Karlén]

Oki, Stefano, can happen to all of us.

Thanks for taking time to try to help, anyway!

Br, Emil

[Emil Karlén]

Hi Matthias, and thanks very much!

I should have followed the structure of the Makefile and put "-c sphinx" in "SPHINXOPTS".

But it is a bit confusing as you say, and point to. Also, "-M" is mentioned in the man page for sphinx-build but it

only says that it must appear first - not that dir arguments must follow.

Anyway, thank you very much for helping me with this, now I have put my conf..py in sphinx/ !

Br

Emil