I was going to add this comment in the main repo, but it is still somewhat raw, so let me just do it here instead.
Here's some thoughts for the plans for this.
There are actually two places that index.rst is relevant. The first is the overall root index.rst for the package. This is the one that we are currently using a jinja template for. We have not yet implemented the changes to allow the user to customize this with an index.rst.jinja, but that is planned.
But now the package text documentation, typically in the doc/ directory, also has an index.rst. Currently this is being generated automatically by searching for renderable documentation, and generating an index.rst that shows all subdirectories containing this documentation. If the user also includes an index.rst file in the doc/ directory, this overwrites the automatically generated one.
There is a single conf.py that is used. The current logic around when we use a user-supplied conf.py, or when we generate a default conf.py, is somewhat confusing.
The way I would like to implement this is: the user can supply a doc/conf.py or a doc/conf.py.jinja file. They can also supply a doc/index.rst file or a doc/index.rst.jinja file. What is used would be in this priority: 1) user doc/conf.py or doc/index.rst if supplied. 2) user doc/conf.py.jinja or doc/index.rst.jinja if supplied, else 3) a default doc/conf.py.jinja or doc/index.rst if the user provided none.
I would also like to allow the user to customize the overall project index.rst file in the same manner.
I was going to add this comment in the main repo, but it is still somewhat raw, so let me just do it here instead.
Here's some thoughts for the plans for this.
There are actually two places that index.rst is relevant. The first is the overall root index.rst for the package. This is the one that we are currently using a jinja template for. We have not yet implemented the changes to allow the user to customize this with an index.rst.jinja, but that is planned.
But now the package text documentation, typically in the doc/ directory, also has an index.rst. Currently this is being generated automatically by searching for renderable documentation, and generating an index.rst that shows all subdirectories containing this documentation. If the user also includes an index.rst file in the doc/ directory, this overwrites the automatically generated one.
There is a single conf.py that is used. The current logic around when we use a user-supplied conf.py, or when we generate a default conf.py, is somewhat confusing.
The way I would like to implement this is: the user can supply a doc/conf.py or a doc/conf.py.jinja file. They can also supply a doc/index.rst file or a doc/index.rst.jinja file. What is used would be in this priority: 1) user doc/conf.py or doc/index.rst if supplied. 2) user doc/conf.py.jinja or doc/index.rst.jinja if supplied, else 3) a default doc/conf.py.jinja or doc/index.rst if the user provided none.
I would also like to allow the user to customize the overall project index.rst file in the same manner.