.. _2023-name:

!!!!
2023
!!!!

.. meta::
   :keywords: 2023,xrst,release,notes,for,mm-dd,12-23,12-20,12-19,12-17,12-10,12-06,12-04,11-21,11-20,11-15,10-18,10-09,10-08,10-07,10-01,09-28,09-07,08-24,08-23,08-17,08-14,07-19,07-17,07-16,07-15,07-10,07-02,06-04,05-27,05-03,04-12,04-02,03-08,02-19,02-05,01-23,01-22,01-19,01-12,01-10,01-08,01-06,01-05,01-03,01-02,01-01

.. index:: 2023, xrst, release, notes, 2023

.. _2023-title:

xrst Release Notes for 2023
###########################

.. contents::
   :local:

.. index:: mm-dd

.. _2023@mm-dd:

mm-dd
*****

.. _2023@mm-dd@12-23:

12-23
=====
Change the python comment delimiter from
``"""`` to ``r"""`` in the following examples:
:ref:`code_example-name` ,
:ref:`indent_example-name` ,  and
:ref:`testExample-name`  .

.. _2023@mm-dd@12-20:

12-20
=====
Improve the :ref:`get_started-name` example.

.. _2023@mm-dd@12-19:

12-19
=====
Improve the summary message about spelling warnings.

.. _2023@mm-dd@12-17:

12-17
=====
#. The discussion of the spell command :ref:`spell_cmd@project_dictionary`
   was improved. In addition, a list of all the misspelled words if included
   after the spelling warnings as a suggestion for the project dictionary.
#. A copy button was added to the all displayed code. This added the
   ``sphinx-copybutton`` to the :ref:`user-guide@Dependencies` .

.. _2023@mm-dd@12-10:

12-10
=====
The :ref:`indent command<indent_cmd-name>` was added so that
the amount of indentation could be different for different parts of a page;
e.g. see :ref:`example_ad_double@xrst_indent` .

.. _2023@mm-dd@12-06:

12-06
=====
#. An example that documents a class was added; see
   :ref:`class_example-name` .
#. The comparison between xrst with doxygen and autodoc was made
   more explicit; see :ref:`purpose@Goal` .
#. The pound sign ``#`` and the dash character ``-`` were added to the list
   of characters allowed in the web address that do not get spell checked.

.. _2023@mm-dd@12-04:

12-04
=====
Words in the current :ref:`spell_cmd@page_name`
are now automatically consider correct spellings and are
no longer needed in the spell command.
If this causes a lot of spelling warnings for a project,
consider using :ref:`run_xrst@replace_spell_commands` to fix them.

.. _2023@mm-dd@11-21:

11-21
=====
Add mention in :ref:`purpose-name` of the new
:ref:`xrst_search<auto_file@xrst_search.rst>` web page.

.. _2023@mm-dd@11-20:

11-20
=====
The program would crash after reporting warning or error when
the :ref:`run_xrst@rst_line_numbers` option was present on the command line.
This has been fixed.

.. _2023@mm-dd@11-15:

11-15
=====
Add the :ref:`xrst_search<auto_file@xrst_search.rst>` web page.

.. _2023@mm-dd@10-18:

10-18
=====
Allow for newlines in sphinx ``ref`` role targets; see
:ref:`ref_cmd-name` .

.. _2023@mm-dd@10-09:

10-09
=====
#. The following problem has been fixed.
   If :ref:`run_xrst@page_source` was not present on the xrst command line,
   and :ref:`run_xrst@target` was tex, the program crashed with the message::

      UnboundLocalError: cannot access local variable 'data_out' ...

#. When ``page_source`` is present and *target* is ``tex`` ,
   the location of the page source file name was changed so it stands out.

#. When *target* was ``tex`` , and there were dash characters ``-`` in a
   :ref:`begin_cmd@page_name` , a cross reference to *page_name*\ ``-name``
   would fail.  This has been fixed.

.. _2023@mm-dd@10-08:

10-08
=====
There was a bug in the conversion of error messages from the
extracted rst file location to the location in the original source file.
The converter did not recognize a :ref:`begin_cmd@page_name` that
had capital letters, A-Z, or the dash character, - .
This has been fixed.

.. _2023@mm-dd@10-07:

10-07
=====
Change html theme from ``sphinx_book_theme`` to ``furo``
because sphinx book theme does not support as many levels; see
`sphinx_book_theme issue 603
<https://github.com/executablebooks/sphinx-book-theme/issues/603>`_ .

.. _2023@mm-dd@10-01:

10-01
=====
There was a bug in the :ref:`run_xrst@replace_spell_commands` option.
To be specific, the program would halt with the following message::

   ... line 92, in replace_spell
   data_copy = xrst.add_line_numbers(data_copy)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ... add_line_numbers() missing 1 required positional argument: 'file_in'

This has been fixed.

.. _2023@mm-dd@09-28:

09-28
=====
Change the :ref:`get_started-name` example to install the current test
version of xrst.

.. _2023@mm-dd@09-07:

09-07
=====
#. Change python doc strings form using ``'''`` and ``"""``
   to using ``r'''`` and ``r"""`` ; e.g, see :ref:`docstring_example-name` .
   This avoids python syntax highlighting in the documentation code
   (in some editors).
#. Remove the ``'''`` form the :ref:`configure_example@This Example File` because
   it is not a python file and so does not need them.

.. _2023@mm-dd@08-24:

08-24
=====
#. The :ref:`heading_links@Labels@Discussion` about labels being verbose
   was improved by splitting the corresponding item into sub-items.
#. The comparison between xrst literal command and the sphinx
   :ref:`literal_cmd@literalinclude` directive was improved.
   To be specific, the following paragraph was added:
   'It is possible to specify multiple sections of a file using the
   start after and end before patterns ...`

.. _2023@mm-dd@08-23:

08-23
=====
If there is an undefined label,
that could not be an xrst :ref:`label <heading_links@Labels>` ,
then following message is added to the warning:

   | The label above does not contain an @ or end with -name or -title.
   | Hence it is not automatically generates by xrst.

.. _2023@mm-dd@08-17:

08-17
=====
Add a link for Read the Docs configuration file
:ref:`specification <.readthedocs.yaml@Read The Docs Specification>` .

.. _2023@mm-dd@08-14:

08-14
=====
#. The :ref:`heading_links@Labels@Discussion` of the html location
   corresponding to a heading was improved. To specific,
   "an html heading location is still valid after changing its
   documentation and/or source code locations" .
#. The optional :ref:`toc_cmd@order` argument was added to the
   table of children command.

.. _2023@mm-dd@07-19:

07-19
=====
Make the ``.in``:ref:`literal_cmd@display_file@extension`
a special case in the literal command.

.. _2023@mm-dd@07-17:

07-17
=====
Fix spell checking inside new version of literal command.

.. _2023@mm-dd@07-16:

07-16
=====
Add an optional :ref:`literal_cmd@separator` to the literal command.

.. _2023@mm-dd@07-15:

07-15
=====
#. Make it an error for the following text to appear in an input file:

   |  ``@xrst_line`` *number*

   where *number* is an integer.
   (This pattern used is used to report line numbers in error messages.)
#. A check was added that will report an error when the text ``{xrst_``
   is not the beginning of a recognized command and
   it is not preceded by a backslash.

.. _2023@mm-dd@07-10:

07-10
=====
#. Fix the ``xrst --help`` message for the :ref:`run_xrst@rename_group` option.
#. Make the order of the ``xrst --help`` output the same as in the command
   :ref:`run_xrst@Syntax` .

.. _2023@mm-dd@07-02:

07-02
=====
#. Move all the command line true / false flags to the beginning of the
   xrst :ref:`run_xrst@Syntax` ; e.g., ``--rst_only`` .
#. Add the :ref:`run_xrst@number_jobs` command line argument
   (for parallel processing).

.. _2023@mm-dd@06-04:

06-04
=====
Fix some spelling errors found when changing pyspellchecker from
version 0.7.0 to 0.7.2.

.. _2023@mm-dd@05-27:

05-27
=====
#. Remove the ``build`` package from the required packages
   (not even needed for testing).
#. Remove the shebang from the ``xrst/run_xrst.py`` file
   because it is not directly executed at the shell command line.

.. _2023@mm-dd@05-03:

05-03
=====
Improve the error message when there is more than one
:ref:`toc_cmd-name` in a page.

.. _2023@mm-dd@04-12:

04-12
=====
The :ref:`comment_ch_example@Discussion` paragraph of the
comment character example was improved.

.. _2023@mm-dd@04-02:

04-02
=====
The ``xrst --help`` message was reporting the wrong help for ``--rst_only``.
This has been fixed. In addition, the
:ref:`run_xrst@rst_only` documentation has been improved.

.. _2023@mm-dd@03-08:

03-08
=====
The program used to abort when a :ref:`toc_cmd-name` did not specify any files.
In the special case where the current page starts with ``begin_parent`` ,
an empty file list can be useful to specify the location of the child links
and the type of children; i.e., hidden, list, or table.

.. _2023@mm-dd@02-19:

02-19
=====
Add the :ref:`run_xrst@continue_with_warnings` command line option.

.. _2023@mm-dd@02-05:

02-05
=====
Improve the :ref:`user-guide@Install Testing Version` instructions
so that it properly fetches the xrst dependencies.

.. _2023@mm-dd@01-23:

01-23
=====

#. If you had a :ref:`toc_cmd-name` with no files,
   e.g. ``{xrst_toc_hidden}`` ,
   the program would crash with the message below.
   This has been fixed by printing a useful error message in this case::

      assert m_child is None

#. The :ref:`.readthedocs.yaml-name` example file was modified to
   show how to use the most recent testing version of xrst.

.. _2023@mm-dd@01-22:

01-22
=====
Add the :ref:`run_xrst@suppress_spell_warnings` command line option.

.. _2023@mm-dd@01-19:

01-19
=====
Add the :ref:`config_file@heading` configuration file option.
This can be used to check that all the pages in a project use the same
underline and overline conventions.

.. _2023@mm-dd@01-12:

01-12
=====
#. Include a temporary fix for the dependency problem
   by including a setup.py file.
   This will no longer be necessary when
   setuptools gets the dependencies right.
#. Change the Development Status in pip from Production to Beta.
#. Simplify :ref:`.readthedocs.yaml-name` (now the dependency problem
   has been fixed).

.. _2023@mm-dd@01-10:

01-10
=====
#. Modify the wish list Testing item (completed on 2024-04-30)
   now that tox and pytest are used to test versions of python.
#. Switch from using hatchling to setuptools as the backend
   for building this project.
#. Add following discussion to install instructions (it has since been removed).
   The `pep-621 <https://peps.python.org/pep-0621>`_ standard
   is for the dependencies to be in the pyproject.toml file.
   Some older versions of setuptools do not yet handle these
   correctly and you may need include some of the dependencies on
   the pip install command line; see
   :ref:`user-guide@Dependencies` .

.. _2023@mm-dd@01-08:

01-08
=====
#. Add the pytest directory and instructions for using it under
   :ref:`user-guide@Install From Source` .
#. Add the :ref:`config_file@spell_package` configure file option.

.. _2023@mm-dd@01-06:

01-06
=====
#. The dash characters ``-`` was added to the characters allowed in a
   :ref:`begin_cmd@page_name` .
   This change will be included in version 2023.0.2.
   The page name user_guide was changed to :ref:`user-guide-name` as
   a demonstration of using dashes in page names.
#. Change the index.html file in the
   :ref:`config_file@directory@html_directory`
   to be a copy of the :ref:`run_xrst@index_page_name` html file
   instead of a redirect to it.
   This was done because firefox cached the redirect and you could not
   change it without clearing all the cache.

.. _2023@mm-dd@01-05:

01-05
=====
Edit the :ref:`wish_list@RST Command File Names` wish list entry.

.. _2023@mm-dd@01-03:

01-03
=====
Add the :ref:`wish_list@Spell Checking` wish list item.

.. _2023@mm-dd@01-02:

01-02
=====
#. If you ran xrst twice with the sphinx_rtd_theme,
   you would get a warning that xrst could not modify the widths in the theme.
   This has been fixed (and will be included in version 2023.0.2).
#. Add :ref:`user-guide@Install From Source` instructions and add more
   discussion to the other installs.

.. _2023@mm-dd@01-01:

01-01
=====
Tried to change the html_theme in :ref:`.readthedocs.yaml-name` from furo
to sphinx_book_theme to get better coloring of code font; see git hash
``2bea5b4fc`` .
This generated a sphinx crash on readthedocs .
