master: get_started.xrst: Use an empty xrst.toml file.

bin/check_xrst.sh

@@ -28,7 +28,13 @@ then
    echo "bin/check_xrst.sh: must be executed from its parent directory"
    exit 1
 fi
-PYTHONPATH="$(pwd):$PYTHONPATH"
+if [ -z ${PYTHONPATH+x} ]
+then
+   export PYTHONPATH="$(pwd)"
+else
+   export PYTHONPATH="$(pwd):$PYTHONPATH"
+fi
+print_variable PYTHONPATH
 # -----------------------------------------------------------------------------
 # number_jobs
 if [ $(nproc) == '1' ] || [ $(nproc) == '2' ]

example/get_started.xrst

@@ -1,8 +1,11 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 # SPDX-FileCopyrightText: Bradley M. Bell <[email protected]>
-# SPDX-FileContributor: 2020-23 Bradley M. Bell
+# SPDX-FileContributor: 2020-24 Bradley M. Bell
 # ----------------------------------------------------------------------------
 {xrst_begin get_started}
+{xrst_spell
+   url
+}
 
 Title: Getting Started
 ######################
@@ -17,19 +20,27 @@ Heading: Steps
 
       pip install xrst
 
-#. Create an empty directory and make it your current working directory.
+#. If you like, you can replace this by the most recent test version
+   of xrst using the following commands::
 
-#. Create a file called ``xrst.toml`` (the xrst configure file)
-   in the working directory with the following contents::
+      pip uninstall -y xrst
+      pip install --index-url https://test.pypi.org/simple/ xrst
 
-      [root_file]
-      default = 'get_started.xrst'
+#. Create an empty directory and make it your current working directory.
 
-   This is the xrst configure file.
+#. Create an empty file called ``xrst.toml`` (the xrst configure file)
+   in the working directory. The empty file tells xrst to use
+   all its default configuration settings.
 
-#. Create a file called ``get_started.xrst``, in the working directory,
+#. Create a file called ``project.xrst``, in the working directory,
    with the contents of
    :ref:`this example file<get_started@Heading: This Example File>` .
+   Note that ``project.xrst`` is the default location for the xrst root file.
+   You could change the location of the root file to  ``get_started.xrst`` 
+   by entering the following in your ``xrst.toml`` file::
+
+      [root_file]
+      default = 'get_started.xrst'
 
 #. Execute the following command::
 
@@ -40,8 +51,12 @@ Heading: Steps
 
       build/html/get_started.html
 
-#. You may have gotten spelling warnings because the spell checker
-   you are using is different from the one used to test xrst.
+#. You may have gotten spelling warnings for two reasons:
+
+   a. The file extension ``toml`` is not in the default project dictionary.
+   b. You are using is different version of the spell checker 
+      from the one used to test xrst.
+
    You can fix these warning by adding or removing words in the
    spell command at the beginning of the get_started.xrst file.
    If you do this correctly and re-execute the xrst command,

test_rst/2024.rst

@@ -5,7 +5,7 @@
 !!!!
 
 .. meta::
-   :keywords: 2024,xrst,release,notes,for,mm-dd,06-25,04-30,04-06,04-05,03-30,03-29,03-28,03-19,03-16,03-04,03-02,03-01,02-29,02-25,02-14,02-03,01-29,01-21,01-04,01-01
+   :keywords: 2024,xrst,release,notes,for,mm-dd,08-12,06-25,04-30,04-06,04-05,03-30,03-29,03-28,03-19,03-16,03-04,03-02,03-01,02-29,02-25,02-14,02-03,01-29,01-21,01-04,01-01
 
 .. index:: 2024, xrst, release, notes, 2024
 
@@ -24,6 +24,15 @@ xrst Release Notes for 2024
 mm-dd
 *****
 
+.. _2024@mm-dd@08-12:
+
+08-12
+=====
+Change the :ref:`get_started-name` example to use an empty ``xrst.toml``
+configuration file. In addition put xrst.toml in the page for the
+:ref:`configuration file<config_file-name>`
+(so that it comes up when you search for xrst.toml).
+
 .. _2024@mm-dd@06-25:
 
 06-25

test_rst/config_file.rst

@@ -5,19 +5,20 @@ config_file
 !!!!!!!!!!!
 
 .. meta::
-   :keywords: config_file,configuration,file,for,xrst,project_name,default,example,directory,project_directory,html_directory,tex_directory,rst_directory,other,generated,files,root_file,spell_package,heading,input_files,input_files.sh,html_theme_options,include_all,rst_epilog,rst_prolog,latex_macro,project_dictionary,not_in_index
+   :keywords: config_file,the,xrst.toml,configuration,file,project_name,default,example,directory,project_directory,html_directory,tex_directory,rst_directory,other,generated,files,root_file,spell_package,heading,input_files,input_files.sh,html_theme_options,include_all,rst_epilog,rst_prolog,latex_macro,project_dictionary,not_in_index
 
 .. _toml file: https://toml.io/en/
 
-.. index:: config_file, configuration, xrst
+.. index:: config_file, xrst.toml, configuration
 
 .. _config_file-title:
 
-Configuration File for xrst
-###########################
+The xrst.toml Configuration File
+################################
 A `toml file`_ is used to configure xrst.
 
-#. The location of this file is specified by the 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.
@@ -52,7 +53,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 58-59
+   :lines: 59-60
    :language: toml
 
 .. _config_file@project_name@Example:
@@ -144,7 +145,7 @@ Note that '.' denotes the directory where
 :ref:`xrst <run_xrst-name>` is run.
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 126-130
+   :lines: 127-131
    :language: toml
 
 .. _config_file@directory@Example:
@@ -176,7 +177,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 161-162
+   :lines: 162-163
    :language: toml
 
 Note that ``default`` corresponds to the
@@ -209,7 +210,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 189-190
+   :lines: 190-191
    :language: toml
 
 .. _config_file@spell_package@Example:
@@ -248,7 +249,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 223-225
+   :lines: 224-226
    :language: toml
 
 .. _config_file@heading@Example:
@@ -301,7 +302,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 273-276
+   :lines: 274-277
    :language: toml
 
 .. _config_file@input_files@Example:
@@ -349,7 +350,7 @@ Default
 The html_theme_options default value below my change in the future.
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 316-321
+   :lines: 317-322
    :language: toml
 
 .. _config_file@html_theme_options@Example:
@@ -415,7 +416,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 377-380
+   :lines: 378-381
    :language: toml
 
 .. _config_file@include_all@Example:
@@ -448,7 +449,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 412-413
+   :lines: 413-414
    :language: toml
 
 .. _config_file@project_dictionary@Example:
@@ -488,7 +489,7 @@ Default
 =======
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 447-448
+   :lines: 448-449
    :language: toml
 
 .. _config_file@not_in_index@Example:

test_rst/get_conf_dict.rst

@@ -28,7 +28,7 @@ Prototype
 *********
 
 .. literalinclude:: ../../xrst/get_conf_dict.py
-   :lines: 504-506,697-699
+   :lines: 505-507,698-700
    :language: py
 
 .. index:: config_file

test_rst/get_started.rst

@@ -31,19 +31,27 @@ Heading: Steps
 
       pip install xrst
 
-#. Create an empty directory and make it your current working directory.
+#. If you like, you can replace this by the most recent test version
+   of xrst using the following commands::
 
-#. Create a file called ``xrst.toml`` (the xrst configure file)
-   in the working directory with the following contents::
+      pip uninstall -y xrst
+      pip install --index-url https://test.pypi.org/simple/ xrst
 
-      [root_file]
-      default = 'get_started.xrst'
+#. Create an empty directory and make it your current working directory.
 
-   This is the xrst configure file.
+#. Create an empty file called ``xrst.toml`` (the xrst configure file)
+   in the working directory. The empty file tells xrst to use
+   all its default configuration settings.
 
-#. Create a file called ``get_started.xrst``, in the working directory,
+#. Create a file called ``project.xrst``, in the working directory,
    with the contents of
    :ref:`this example file<get_started@Heading: This Example File>` .
+   Note that ``project.xrst`` is the default location for the xrst root file.
+   You could change the location of the root file to  ``get_started.xrst``
+   by entering the following in your ``xrst.toml`` file::
+
+      [root_file]
+      default = 'get_started.xrst'
 
 #. Execute the following command::
 
@@ -54,8 +62,12 @@ Heading: Steps
 
       build/html/get_started.html
 
-#. You may have gotten spelling warnings because the spell checker
-   you are using is different from the one used to test xrst.
+#. You may have gotten spelling warnings for two reasons:
+
+   a. The file extension ``toml`` is not in the default project dictionary.
+   b. You are using is different version of the spell checker
+      from the one used to test xrst.
+
    You can fix these warning by adding or removing words in the
    spell command at the beginning of the get_started.xrst file.
    If you do this correctly and re-execute the xrst command,

test_rst/xrst_contents.rst

@@ -36,7 +36,7 @@ Table of Contents
 |    :ref:`1.18<testExample-title>` Test Special Conditions
 | :ref:`2<purpose-title>` Purpose of this Sphinx Wrapper
 | :ref:`3<user-guide-title>` Extract Sphinx RST Files
-|    :ref:`3.1<config_file-title>` Configuration File for xrst
+|    :ref:`3.1<config_file-title>` The xrst.toml Configuration File
 |    :ref:`3.2<run_xrst-title>` Extract RST Files And Run Sphinx
 |    :ref:`3.3<commands-title>` Commands
 |       :ref:`3.3.1<begin_cmd-title>` Begin and End Commands

user/2024.xrst

@@ -21,6 +21,13 @@ xrst Release Notes for 2024
 mm-dd
 *****
 
+08-12
+=====
+Change the :ref:`get_started-name` example to use an empty ``xrst.toml``
+configuration file. In addition put xrst.toml in the page for the
+:ref:`configuration file<config_file-name>` 
+(so that it comes up when you search for xrst.toml).
+
 06-25
 =====
 It used to be the case that the following input would cause xrst to crash

xrst/get_conf_dict.py

@@ -27,11 +27,12 @@ def system_exit(msg) :
 
 .. _toml file: https://toml.io/en/
 
-Configuration File for xrst
-###########################
+The xrst.toml Configuration File
+################################
 A `toml file`_ is used to configure xrst.
 
-#. The location of this file is specified by the 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.