How to generate index.rst alone or generate everything excluding conf.py by sphinx-apidocs?

Question

I understand that the following generates rst for all modules, excluding the index.rst

sphinx-apidoc -f -o very_good_docs/ very_good

And the following generates everything, including index.rst, conf.py, Makefile, etc

sphinx-apidoc -F -f -o very_good_docs/ very_good

The problem is that sphinx-apidoc does not generate a correct conf.py, so I have to always manually modify conf.py to include the correct sys.paths. If I modify my python code in "very_good" folder, I should run the sphinx-apidoc command without "-F", so conf.py is preserved. However, if I add a new module under very_good directly, index.rst is not updated without the "-F" option, which means my new module will not be in the doc. I guess the solution is to either someone generates the index.rst file only, or using "-F" option without overriding the conf.py. Is there a way to do it?

Answer 1

This is something I'm experiencing right now. It's really frustrating not finding information to achieve something so common.

My approach is to use a custom config.py and specifying it always I execute sphinx-build with the -F option. This way my config.py is not overwritten even if a new (and useless) config.py is created.

In order to specify a custom config.py you should use the -c option as stated in the documentation:

-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.

The command will look like this:

sphinx-build -b html -c %sphinxConfigDir% %sourceCode% %buildDir%