\(\newcommand{\B}[1]{ {\bf #1} }\) \(\newcommand{\R}[1]{ {\rm #1} }\)

config_file

View page source

The xrst.toml Configuration File

A toml file is used to configure xrst.

1. The default location for this file is xrst.toml . You can specify a different location using the config_file argument.

2. This file is a sequence of toml tables, if a table can only have one entry, the entry is named data.

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

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

project_name

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

Default

[project_name]
data = 'project'

Example

[project_name]
data = 'xrst'

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 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 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 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 page_name , the file If this directory does not exist, it will be created.

  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 Automatically Generated Files for the other files generated by xrst and placed in the rst_directory.

Default

Note that '.' below denotes the directory where the config_file is located.

[directory]
project_directory  = '.'
rst_directory      = 'build/rst'
html_directory     = 'build/html'
tex_directory      = 'build/tex'

Example

[directory]
# This is same as the default and only used as an example
project_directory = '.'
rst_directory     = 'build/rst'
html_directory    = 'build/html'
tex_directory     = 'build/tex'

root_file

This table maps each group_name to its root (top) xrst input file. These file names are relative to the project_directory . Multiple groups can use the same root file.

Default

[root_file]
default = 'project.xrst'

Note that default corresponds to the Default Group and project.xrst is the default root file.

Example

[root_file]
default = 'example/example.xrst'
user    = 'user/user.xrst'
dev     = 'xrst/__init__.py'

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

[spell_package]
data = 'pyspellchecker'

Example

# [spell_package]
# This is commented out because pyenchant is harder to set up on some systems:
# data = 'pyenchant'

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

Default

[heading]
character = []
overline  = []

Example

# If running an old verison of xrst that does not support heading,
# comment out the lines from [heading] to overline =.
[heading]
#   level         0,     1,     2,     3,     4,
character = [   '#',   '*',   '=',   '-',   '.',  ]
overline  = [ false, false, false, false, false,  ]

input_files

This table is used to list the files that should be include in the documentation if they have a begin command for a group in 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

[input_files]
data = [
   [ 'git', 'ls-files' ]
]

Example

[input_files]
data = [
   [ 'bin/input_files.sh' ] ,
]

input_files.sh

#! /usr/bin/env bash
set -e -u
#
# git ls-files: list files in the git repository
# sed:          remove files in the test_rst directory
git ls-files | sed -e '/^test_rst[/]/d'

html_theme_options

This table maps the 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.

[html_theme_options.sphinx_book_theme]
show_toc_level = 4

[html_theme_options.sphinx_rtd_theme]
navigation_depth = -1
titles_only        = true

Example

# This is same as the default and only used as an example
[html_theme_options.sphinx_book_theme]
show_toc_level = 4

[html_theme_options.sphinx_rtd_theme]
navigation_depth = -1
titles_only      = true

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 target is html.

latex_macro

The value corresponding to this key is a list of latex macros. If 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

[include_all]
rst_epilog = ''
rst_prolog = ''
latex_macro  = []

Example

[include_all]
rst_epilog = ''
rst_prolog = '''
.. |space| unicode:: 0xA0
.. |tab| replace:: |space| |space| |space|
'''
latex_macro = [
   '\newcommand{\B}[1]{ {\bf #1} }' ,
   '\newcommand{\R}[1]{ {\rm #1} }' ,
]

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

Default

[project_dictionary]
data = []

Example

[project_dictionary]
data = [
   # keywords in souce code languages
   '''
   bool
   def
   dict
   int
   str
   ''',
   # file extensions
   '''
   py
   rst
   toml
   ''',
   # abbreviations
   # dir:   used for directory (as part of a variable name)
   # obj:   used for object (as appossed to the corresponding class)
   # tmp:   is used for temparary values
   # toc:   used for table of contents or table of children
   # dd-mm: used for day and month as two decimal characters
   '''
   dir
   obj
   tmp
   toc
   dd
   mm
   ''',
   # special words
   '''
   boolean
   meta
   newline
   newlines
   overline
   pyspellchecker
   xrst
   ''',
]

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

[not_in_index]
data = []

Example

[not_in_index]
data = [
  # articles, prepositions, and common verbs
  '''
      a
      an
      and
      been
      by
      for
      has
      of
      that
      the
      this
      to
  ''',
  # words that are use in many different pages of the documentation
  '''
    command
    example
    file
    purpose
    syntax
  ''',
  # python regular expression for month-day used in release notes
  '[0-9]{2}-[0-9]{2}',
  # python regular expression for year.month.day used in version number
  '[0-9]{4}[.][0-9]{1,2}[.][0-9]{1,2}',
]