-------------------------------------------
lines 17-464 of file: xrst/get_conf_dict.py
-------------------------------------------

{xrst_begin config_file user}
{xrst_spell
   booleans
   conf
   overlined
   overlining
   pyenchant
   rtd
}

.. _toml file: https://toml.io/en/

The xrst.toml Configuration File
################################
A `toml file`_ is used to configure xrst.

#. The default location for this file is ``xrst.toml`` .
   You can specify a different location using the
   :ref:`run_xrst@config_file` argument.
#. This file is a sequence of toml tables,
   if a table can only have one entry, the entry is named data.
#. Each table has a default value that is used when the table
   is not present in the toml file.
   All of the defaults below will be the same in future versions
   of xrst with the possible exception of the html theme options
   :ref:`config_file@html_theme_options@Default` .
#. All of the entries in a table have the same type
   as its corresponding default.
   If an entry has components, all of the comments have the same
   type as the default components.
   The html theme options default is one exception to this rule; see
   :ref:`config_file@html_theme_options` .
{xrst_comment --------------------------------------------------------------- }

project_name
************
The only value in this table is the name of this project.

Default
=======
{xrst_code toml}
[project_name]
data = 'project'
{xrst_code}
{xrst_suspend}'''
default_dict['project_name'] = { 'data' : 'project' }
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_PROJECT_NAME
   # END_PROJECT_NAME
}
{xrst_comment --------------------------------------------------------------- }

directory
*********
This table specifies the locations of some xrst directories:

project_directory
=================
This *project_directory* can be an absolute path,
or a path relative to the location where the
:ref:`run_xrst@config_file` is located.
All of the other directories are specified relative to this directory.
The other directories may have ``../`` in their specifications; i.e.,
they do not need to be sub-directories of the project directory.
This directory must exists when xrst is run.

html_directory
==============
This is the directory, relative to the *project_directory*,
where the output files are stored when
:ref:`run_xrst@target` is ``html`` .
If *target* is html and this directory does not exist, it will be created.

tex_directory
=============
This is the directory, relative to the *project_directory*,
where the output files are stored when
:ref:`run_xrst@target` is ``tex`` .
If *target* is tex and this directory does not exist, it will be created.

rst_directory
=============
This is the directory, relative to the *project_directory*,
where xrst writes the rst files it extracts from the source code.
For each :ref:`begin_cmd@page_name` , the file
If this  directory does not exist, it will be created.

|space| *rst_directory*\ /\ *page_name*\ ``.rst``

is the RST file for the corresponding page. There is one exception
to this rule. If *page_name* ends with ``.rst``, the extra ``.rst``
is not added at the end.

Other Generated Files
---------------------
See :ref:`auto_file-title` for the other files generated by ``xrst``
and placed in the *rst_directory*.

Default
=======
Note that ``'.'`` below denotes the directory where the
:ref:`run_xrst@config_file` is located.

{xrst_code toml}
[directory]
project_directory  = '.'
rst_directory      = 'build/rst'
html_directory     = 'build/html'
tex_directory      = 'build/tex'
{xrst_code}
{xrst_suspend}'''
default_dict['directory'] = {
   'project_directory' : '.'    ,
   'rst_directory'     : 'build/rst'  ,
   'html_directory'    : 'build/html' ,
   'tex_directory'     : 'build/tex'  ,
}
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_DIRECTORY
   # END_DIRECTORY
}
{xrst_comment --------------------------------------------------------------- }

root_file
*********
This table maps each :ref:`begin_cmd@group_name`
to its root (top) xrst input file.
These file names are relative to the
:ref:`config_file@directory@project_directory` .
Multiple groups can use the same root file.

Default
=======
{xrst_code toml}
[root_file]
default = 'project.xrst'
{xrst_code}
{xrst_suspend}'''
default_dict['root_file'] = { 'default' : 'project.xrst' }
r'''{xrst_resume}

Note that ``default`` corresponds to the
:ref:`begin_cmd@group_name@Default Group` and ``project.xrst``
is the default root file.

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_ROOT_FILE
   # END_ROOT_FILE
}
{xrst_comment --------------------------------------------------------------- }

spell_package
*************
This str is either 'pyspellchecker' or 'pyenchant' .
These are the only spell checkers support so far.
If it is not the default,
you may need to use pip to install the spell checker that you use.

Default
=======
{xrst_code toml}
[spell_package]
data = 'pyspellchecker'
{xrst_code}
{xrst_suspend}'''
default_dict['spell_package'] = { 'data' : 'pyspellchecker' }
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_SPELL_PACKAGE
   # END_SPELL_PACKAGE
}
{xrst_comment --------------------------------------------------------------- }

heading
*******
This table can be used to check that the underlining and overlining
of headings is consistent for all pages.
This table has two lists,
one named ``character`` the other named ``overline``.
These list must have the same length and only headings up the
that level are checked.
The elements of the character list have type string and are used
to check the underline character at each heading level.
The elements of the overline list have type Boolean and are used
to check if the heading is overlined at each heading level.
The first entry in each list is level zero and corresponds to
:ref:`page titles <heading_links@Labels@Level Zero@page_title>` .

Default
=======
{xrst_code toml}
[heading]
character = []
overline  = []
{xrst_code}
{xrst_suspend}'''
default_dict['heading'] = { 'character' : [], 'overline' : [] }
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_HEADING
   # END_HEADING
}

{xrst_comment --------------------------------------------------------------- }

input_files
***********
This table is used to list the files that should be include in the
documentation if they have a :ref:`begin command<begin_cmd-name>`
for a group in :ref:`run_xrst@group_list` .
The only value in this table is a list of program commands.

Each program command is a list of strings.
The list is the program to execute followed by
the program's command line arguments in order.
The standard output for the program should be a space separated
list of file names to be checked.
If a file name has spaces in it, it should be surrounded by single
or double quotes.
The single and double quotes are not part of the file name.
If this list of strings is empty, no files are checked.

Each program is execute, in order, with the *project_directory*
as the current working directory.
The first program to return without an error is used for the list of files.
The intention here is that different programs
may be intended for different systems.

If the list of program commands is empty,
no checking of input file list is done.
If the list of program commands is non-empty,
and none of the program commands succeed,
a warning is printed.

Default
=======
{xrst_code toml}
[input_files]
data = [
   [ 'git', 'ls-files' ]
]
{xrst_code}
{xrst_suspend}'''
default_dict['input_files'] = { 'data' : [
   [ 'git', 'ls-files'] ,
] }
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_INPUT_FILES
   # END_INPUT_FILES
}

input_files.sh
==============
{xrst_literal
   bin/input_files.sh
}
{xrst_comment --------------------------------------------------------------- }

html_theme_options
******************
This table maps the :ref:`run_xrst@html_theme` to
the corresponding html_theme_options.
This enable building documentation with different themes without
having to change the toml file between builds.
If *html_theme* does not appear in this mapping, no options are set.

For each theme, the corresponding options are in a dictionary.
The keys of this dictionary are strings, but the values do not
necessarily have the same type as he default case.
In the default below, these values are integers and booleans.

Default
=======
The html_theme_options default value below my change in the future.
{xrst_code toml}
[html_theme_options.sphinx_book_theme]
show_toc_level = 4

[html_theme_options.sphinx_rtd_theme]
navigation_depth = -1
titles_only        = true
{xrst_code}
{xrst_suspend}'''
default_dict['html_theme_options'] = {
   'sphinx_book_theme' : {
      'show_toc_level' : 4
   },
   'sphinx_rtd_theme'  : {
      'navigation_depth' : -1   ,
      'titles_only'      : True ,
   },
}
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_HTML_THEME_OPTIONS
   # END_HTML_THEME_OPTIONS
}
{xrst_comment --------------------------------------------------------------- }

include_all
***********
This table is used to create input that is included
at the beginning or end of every page.
This table has the following keys:

rst_epilog
==========
The value corresponding to this key is a set of rst commands
that get included at the end of every section.
This is the same as the rst_epilog variable in the sphinx conf.py file.

rst_prolog
==========
The value corresponding to this key is a set of rst commands
that get included at the beginning of every section.
This is the same as the rst_epilog variable in the sphinx conf.py file
except that the latex macros are added at the end when
:ref:`run_xrst@target` is html.

latex_macro
===========
The value corresponding to this key is a list of latex macros.
If :ref:`run_xrst@target` is ``html``, these macros get included at the
beginning of every page using the sphinx ``:math`` role in the
rst_epilog variable in the sphinx conf.py file.
Otherwise *target* is ``tex`` and these macros get included once
at the beginning of the corresponding latex document.
It either case they can be used by every page in the documentation.

Default
=======
{xrst_code toml}
[include_all]
rst_epilog = ''
rst_prolog = ''
latex_macro  = []
{xrst_code}
{xrst_suspend}'''
default_dict['include_all'] = {
      'rst_epilog'   : ''     ,
      'rst_prolog'   : ''     ,
      'latex_macro'  : list() ,
}
r'''{xrst_resume}


Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_INCLUDE_ALL
   # END_INCLUDE_ALL
}
{xrst_comment --------------------------------------------------------------- }

project_dictionary
******************
The only value in this table is a list of strings.
Each string contains a newline separated list of words.
Leading and trailing white space is not part of each word.
These special words are not considered spelling errors for the entire project.
Special words, for a particular page, are specified using the
:ref:`spell command<spell_cmd-name>`.

Default
=======
{xrst_code toml}
[project_dictionary]
data = []
{xrst_code}
{xrst_suspend}'''
default_dict['project_dictionary'] = { 'data' : list() }
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_PROJECT_DICTIONARY
   # END_PROJECT_DICTIONARY
}
{xrst_comment --------------------------------------------------------------- }

not_in_index
************
The only value in this table is a list of strings.
Each string  contains a newline separated list of patterns.
Leading and trailing white space is not part of each pattern.
These are python regular expression patterns for heading tokens
that are not included in the index.
A heading token is any sequence of non white space characters
with upper case letters converted to lower case.
For example, a heading might contain the token ``The`` but you
might not want to include ``the`` as a entry in the :ref:`genindex`.
In this case you could have a line containing just ``the`` .
For another example, you might want to exclude all tokens that are
integer numbers.
In this case you could have a line containing just ``[0-9]*`` .

Default
=======
{xrst_code toml}
[not_in_index]
data = []
{xrst_code}
{xrst_suspend}'''
default_dict['not_in_index'] = { 'data' : list() }
r'''{xrst_resume}

Example
=======
{xrst_literal
   xrst.toml
   # BEGIN_NOT_IN_INDEX
   # END_NOT_IN_INDEX
}

{xrst_end config_file}