From c390cc6c39558bb4d84ad16f446ed11503fc3840 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Mon, 12 Aug 2024 15:14:29 -0700 Subject: [PATCH] master: get_started.xrst: Use an empty xrst.toml file. --- bin/check_xrst.sh | 8 +++++++- example/get_started.xrst | 35 +++++++++++++++++++++++++---------- test_rst/2024.rst | 11 ++++++++++- test_rst/config_file.rst | 31 ++++++++++++++++--------------- test_rst/get_conf_dict.rst | 2 +- test_rst/get_started.rst | 30 +++++++++++++++++++++--------- test_rst/xrst_contents.rst | 2 +- user/2024.xrst | 7 +++++++ xrst/get_conf_dict.py | 7 ++++--- 9 files changed, 92 insertions(+), 41 deletions(-) diff --git a/bin/check_xrst.sh b/bin/check_xrst.sh index 48d5fc6..a2d80fc 100755 --- a/bin/check_xrst.sh +++ b/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' ] diff --git a/example/get_started.xrst b/example/get_started.xrst index 53ea9d6..d4375b8 100644 --- a/example/get_started.xrst +++ b/example/get_started.xrst @@ -1,8 +1,11 @@ # SPDX-License-Identifier: GPL-3.0-or-later # SPDX-FileCopyrightText: Bradley M. Bell -# 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` . + 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, diff --git a/test_rst/2024.rst b/test_rst/2024.rst index 3e42242..3e3e4b1 100644 --- a/test_rst/2024.rst +++ b/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` +(so that it comes up when you search for xrst.toml). + .. _2024@mm-dd@06-25: 06-25 diff --git a/test_rst/config_file.rst b/test_rst/config_file.rst index 4078ede..b09ba2f 100644 --- a/test_rst/config_file.rst +++ b/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 ` 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: diff --git a/test_rst/get_conf_dict.rst b/test_rst/get_conf_dict.rst index 8600fff..d6cd22e 100644 --- a/test_rst/get_conf_dict.rst +++ b/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 diff --git a/test_rst/get_started.rst b/test_rst/get_started.rst index 70afc4c..2d16c7f 100644 --- a/test_rst/get_started.rst +++ b/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` . + 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, diff --git a/test_rst/xrst_contents.rst b/test_rst/xrst_contents.rst index b6c5d6c..44be790 100644 --- a/test_rst/xrst_contents.rst +++ b/test_rst/xrst_contents.rst @@ -36,7 +36,7 @@ Table of Contents | :ref:`1.18` Test Special Conditions | :ref:`2` Purpose of this Sphinx Wrapper | :ref:`3` Extract Sphinx RST Files -| :ref:`3.1` Configuration File for xrst +| :ref:`3.1` The xrst.toml Configuration File | :ref:`3.2` Extract RST Files And Run Sphinx | :ref:`3.3` Commands | :ref:`3.3.1` Begin and End Commands diff --git a/user/2024.xrst b/user/2024.xrst index 77a5a2c..731bd66 100644 --- a/user/2024.xrst +++ b/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` +(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 diff --git a/xrst/get_conf_dict.py b/xrst/get_conf_dict.py index 6cf26c4..8ab28e1 100644 --- a/xrst/get_conf_dict.py +++ b/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.