.. _auto_file-name:

!!!!!!!!!
auto_file
!!!!!!!!!

.. meta::
  :keywords: auto_file,automatically,generated,files,conf.py,xrst_root_doc.rst,xrst_contents.rst,xrst_index.rst,xrst_search.rst,xrst_search.js

.. index:: auto_file, automatically, generated, files

.. _auto_file-title:

Automatically Generated Files
#############################

#. These files are located in the :ref:`config_file@directory@rst_directory` .
#. A new version of these files is created each time ``xrst`` is run.
#. The files in the ``rst`` subdirectory that do not change are not replaced.
   (This reduces the amount of processing that sphinx needs to do.)
#. All these files have the ``.rst`` extension with the exception of
   conf.py and xrst_search.js .

.. contents::
  :local:

.. index:: conf.py

.. _auto_file@conf.py:

conf.py
*******
This is the sphinx configuration_ file.
It is the only file in the *rst_directory* directory that is
not an rst file.

.. _configuration:  http://www.sphinx-doc.org/en/master/config

.. index:: xrst_root_doc.rst

.. _auto_file@xrst_root_doc.rst:

xrst_root_doc.rst
*****************
This file is the top of the documentation tree
built by sphinx. It is one level above the first page in
:ref:`config_file@root_file`.

.. index:: xrst_contents.rst

.. _auto_file@xrst_contents.rst:

xrst_contents.rst
*****************
This file contains the table of contents for the last run of ``xrst``.
You can link to the corresponding
page name :ref:`xrst_contents-name`
or page title :ref:`xrst_contents-title`
with the following commands::

   :ref:`xrst_contents-name`
   :ref:`xrst_contents-title`

.. index:: xrst_index.rst

.. _auto_file@xrst_index.rst:

xrst_index.rst
**************
If :ref:`run_xrst@target` is html,
this file contains a link to the table of contents generated by sphinx.
You can link to the corresponding page name or page title
with the following commands::

   :ref:`xrst_index-name`
   :ref:`xrst_index-title`

The xrst_index.rst file is not created when target is tex.

.. index:: xrst_search.rst

.. _auto_file@xrst_search.rst:

xrst_search.rst
***************
If :ref:`run_xrst@target` is html,
this file contains the xrst search utility for the last run of ``xrst``.
A link to this search utility appears at top left side of each web page.
You can place a link to this page name :ref:`xrst_search-name`
or page title :ref:`xrst_search-title` using the following commands::

   :ref:`xrst_search-title`
   :ref:`xrst_search-name`

This page tile will start with the :ref:`config_file@project_name`
(which for this documentation is ``xrst`` ).
The xrst_search.rst file is not created when target is tex.

.. index:: xrst_search.js

.. _auto_file@xrst_search.js:

xrst_search.js
**************
This file is used by xrst_search.rst.
