CODEWITHSUNDEEP
pythonpython-sphinx
MiniMe
MiniMe

Reputation: 211

Change sphinx-build master file

Can I tell sphinx-build stop looking for index.rst.

$ echo 'test' > readme.rst
$ sphinx-build -C . ./build readme.rst

This wil complain about a missing index file

master file /.../index.rst not found

However we could sort of fix this

$ ln -s readme.rst index.rst
$ sphinx-build -C . ./build readme.rst

This will actually build both index.rst and readme.rst and it will complain that readme.rst is not included in any toc tree. Which could be fixed by using mv instead of ln. However I don't want to move files around just to satisfy the wierd need for sphinx-build to have an index file. I also don't want to have lingering link all over the place either.

Can I change the location of the master file? Something like (which does not work):

$ sphinx-build -C -D 'master_file=readme.rst' . ./build

Or can I tell it to skip the index file all together? Something such as (which does not work):

$ sphinx-build -C -D 'exclude_patterns=index.rst' . ./build readme.rst

Or is there another way around this problem?

Upvotes: 1

Views: 1379

Answers (2)

Steve Piercy
Steve Piercy

Reputation: 15055

First rename your index.rst to readme.rst.

Then you may specify the master_doc configuration option either in your conf.py and build your docs or by overriding that value in your conf.py on the command line when building your docs.

Specified in conf.py

$ sphinx-build . ./build

Specified on command line only

$ sphinx-build . ./build -D master_doc='master'

Upvotes: 2

John Palmieri
John Palmieri

Reputation: 1696

How about:

sphinx-build -C . ./build readme.rst -D master_doc='readme'

In more detail:

$ ls
readme.rst
$ sphinx-build -C . ./build readme.rst -D master_doc='readme'
Running Sphinx v1.8.5
making output directory...
building [mo]: targets for 0 po files that are specified
building [html]: 1 source files given on command line
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] readme                                                          
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] readme                                                           
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build.
$ ls
build       readme.rst

The same thing worked for me with Sphinx 3.0.2.

Upvotes: 1

Related Questions