2022

View page source

xrst Release Notes for 2022

mm-dd

12-31

  1. Bring get_started up to date with current xrst. To be specific, Install Stable Version, correct location of get_started.html, and fix setting of input_files.

  2. The toc_table command was changed to use Name instead of Child as the heading for the page name column.

  3. The index_page_name option was added to the command line.

12-30

  1. Add the rst_only option.

  2. Change to name of the root level file back to index and prohibit a page_name from being index.

  3. Change the default html, tex, and rst directory to be build/html, build/tex, and build/rst respectively.

  4. Add the .readthedocs.yaml example.

  5. Create the first stable install .

12-22

Add the Theme wish list item, and a warning that corresponding html theme options Default may change in the future.

12-20

It used to be that processing was terminated when a warning occurred. This could end up with the output rst files being reported as the source files. This has been fixed and xrst now completes its processing and exits with non-zero status (when a warning occurs).

12-16

  1. Add a comparison between the xrst literal command and the sphinx literalinclude directive.

  2. Update the RST Command File Names wish list entry.

12-15

  1. Change start to start_after and stop to end_before so that the xrst literal command is more like the rst literalinclude directive.

  2. Change the get_started example so that is uses the name get_started.xrst for its input file and so it has a link to the text that goes in this file.

  3. Add the dir command .

12-14

  1. Change the page sources to be the proper section of the xrst input files, instead of the extracted rst files.

  2. Change conf_file to config_file .

  3. Add the page_source option.

  4. Make the project_directory relative to where the configuration file is located, not where the xrst is run.

  5. Change html/index.html to html/get_started.html in get_started (index.html no longer works and get_started.html is a better place to start).

  6. Fix the group_list Example command for building the xrst developer documentation (remove xrst.xrst from command line).

  7. Fix case were an input_files command includes a binary file in its list. (If a file cannot be read as text, it is ignored.)

12-12

  1. Remove dependency on import dismod_at. This was a mistake added when input_files was added to the configuration files yesterday.

  2. Fix default value of input_files and include_all .

  3. Make git ls-files the default input_files command and add discussion of warning about input_files in get_started example.

12-11

  1. Add condition that group_name must be a sequence of the letters a-z to the documentation. Check this condition in the root_file settings.

  2. Add the input_files command to the configuration file.

12-10

  1. Remove the Sphinx Error Messages with list entry because it was completed on 11-13.

  2. Add the View Page Sources wish list entry (which was completed on 11-14 ).

  3. Change the configuration file preamble table to the include_all table and change the rst_substitution name to rst_prolog .

  4. Improve The xrst.toml Configuration File error messaging.

  5. It is now ok for a page_name to be index (it still cannot be genindex ).

12-09

Add the rename_group command line option.

12-08

Change the group_list so that each element of the list is a separate command line argument (instead of one command line argument with commas separating entries).

12-05

  1. Document the fact that project_directory must exist and the other directories will be created in they do not exist.

  2. Fix creation of rst_directory so that it will create parent directories (if necessary); e.g., if it is build/rst it may need to create build.

  3. Change pdf_directory to tex_directory and do not automatically run the latex to pdf conversion; see the tex target discussion.

  4. The comment_cmd was replaced by a space when it was at the beginning of a line and there was text after it on the same line. This has been fixed.

  5. The line number errors were not being translated from rst files to corresponding xrst input files when target was tex . This has been fixed.

  6. Edit the Features description of xrst. To be more specific, describe the two levels of tables of contents and how choosing the html theme works.

12-1

  1. Add the restriction that a page_name cannot be genindex .

  2. Add some common verbs to the configure file not_in_index Example

  3. Check that labels define used sphinx commands do not contain @ or end with -name or -title . This makes them easy to distinguish form labels generated by xrst.

11-30

  1. Create a directory table in the toml configuration file and put the project_directory , rst_directory , html_directory , and pdf_directory setting there.

  2. Change the toml_path command line argument to config_file because it no longer specifies the project_directory .

  3. Change the output_dir command line argument to the choice of html_directory and pdf_directory in the toml configuration file.

  4. Fix path resolution so that rst_directory may contain ../ ; i.e., it need not be a sub-directory of the project directory.

  5. If target is pdf , run latex twice to properly resolve cross references.

  6. Change the toml file directories to be sub-directories of the build directory (except for the project directory).

11-29

  1. Improve the toc_list Example Parent Page , this includes improving its child pages.

  2. If target is pdf, the page name is added to the front of the page title (because one my end up there by selecting the page name for link).

11-28

  1. The automatically generated page_name label was changed from page_name to page_name -name . This makes it easy identify the xrst automatically generated labels.

  2. If target is pdf, the page_name is no longer displayed as a separate heading above the page_title .

11-27

Fix a problem in the latex preamble section of conf.py . This problem started on 11-23 when the toml file preamble was split up the latex macros and the substitutions.

11-26

The output directory specification was moved from the xrst toml file to the xrst command line. It was moved back to output_dir and later replaced by html_directory and pdf_directory . This undid one of the changes on 11-19 . THe

11-24

Enable the use of upper case letters in a page_name. As an example, change test_example to testExample .

11-23

  1. The toml file preamble table was changed to separately specify the rst substitutions and the latex macros.

  2. Add the configure_example page and improve the get_started page.

  3. Add the html_theme_options table was added, html_theme was changed to allow for any theme, and the local_toc was added. If you were using sphinx_rtd_theme, you will have to include the --local_toc command line argument to get the same results as you used to.

11-22

The config_file was changed to be a sequence of tables. If a table only has one entry, the entry is named data.

11-21

  1. No longer necessary to create a sub-directory called sphinx in the get_started example.

  2. Use xrst.toml as the default value for config_file .

  3. Change the command link argument flags to use full names; i.e., change –html -> –html_theme and –group -> –group_list .

  4. Change the suspend_example to demonstrate documenting in one language and implementing in a different language.

11-20

  1. Change the root_file command line argument to toml_path on 11-30 it was changed to config_file .

  2. Add project_name and root_file to the toml file.

  3. Use the notation project_directory for the directory that all the xrst file name are relative to.

11-19

  1. The Default Group is now represented by default in the group_list command line argument.

  2. The wish list configuration item was completed using config_file .

    1. The output_dir command line argument was replaced by output_directory in the config_file file.

    2. The sphinx_dir command line argument was replaced by rst_directory in the config_file file.

    3. The preamble.rst file was replaced by the preamble section of the config_file file.

    4. The spelling file was replaced by the project_dictionary section of the config_file file.

    5. The keyword file was replaced by the not_in_index section of the config_file file.

11-18

  1. The literal_cmd has been extended to work with the file extension *.txt (it is mapped to no highlighting).

  2. The discussion of double word errors was improved.

  3. The detection of duplicate labels in a page was detecting label definitions inside of literal blocks. This was an error and has been fixed.

  4. Mention the difference between the xrst literal display_file name and the sphinx literalinclude file name.

11-16

The xrst spell checking was including the display_file name in the one argument Literal Command . This has been fixed; i.e., display_file is no longer checked for spelling errors.

11-15

  1. Add the rst_line_numbers option.

  2. There was a problem when a space followed a colon in a header. This has been fixed; for example see Heading: Links to this Page .

  3. In the heading to label the at sing @ is converted to a dash - (it used to be converted to an underbar _ ). This makes it more link that Label To Anchor conversion.

11-14

  1. The Label To Anchor conversion was changed to include the page name in the anchor. This reduced the chance of headings having the same anchor.

  2. The error message when two labels have the same anchor was improved. This includes labels defined by sphinx commands and automatically generated xrst Labels for each heading.

11-13

  1. The sphinx error messages were using line numbers in the rst files created by xrst. These line numbers have been converted to the original xrst input files.

  2. The command line argument rst_line was removed because the error line numbers are now automatically converted and so there is no need for a conversion table.

11-05

There was a python breakpoint just before the call to display an xrst syntax error (so the error message was not displayed). This has been fixed.

11-01

  1. Change the label for a page title from page_name -0 to page_name -title .

  2. Improve the heading_links and heading_example discussion of the labels that display the page name and page title

10-31

  1. Add a description of the conversion of Label To Anchor and make it an error for two labels the have the same anchor.

  2. Improve the group list Example .

  3. If for a single group there was more then on page in the root_file and the first such page not a parent for the others, the other pages were not included in the documentation. This has been fixed.

10-29

  1. The program used to generate the assert below when there was no newline at the end of an input file. This has been fixed:

    File .. add_line_numbers.py ...
   assert previous == len(data_in) - 1

  2. The list example was removed and the testExample was added.

  3. The required packages were not being automatically installed because they were under the wrong heading in the pyproject.toml file. This has been fixed.

10-24

  1. Improve spell command documentation and Spell Checking documentation in the code command.

  2. Fix mistaken report of double word error when there was a command, that does not get checked for spelling, between the two words.

10-23

Add {xrst_spell_off} and {xrst_spell_on} to the spell Syntax .

10-21

When there is more than one version of the syntax for a command use a list to separate the different versions of the syntax; e.g., see Syntax for the toc command.

10-11

Add an rst Comments example and compare it to xrst Comments .

10-05

Fix some spelling errors found when changing pyspellchecker from version 0.6.3 to 0.7.0.

10-04

  1. The Heading@To@Label of headings was changed to not convert colons : .

  2. The preamble.rst example file was change to use three (instead of four) spaces for a tab.

  3. Add a substitution and latex macro in the preamble.rst example file.

10-03

  1. The local table of contents was moved after the text below the title amd just before the first heading link (when html_theme is sphinx_rtd_theme ).

  2. The Heading@To@Label of headings was changed to remove backslashes from labels.

10-02

Remove the developer documentation wish list item because it was completed on 09-21 .

09-26

An Underbar can be used at the end of a title if it is escaped with a backslash. So remove the error message for this case; see 09-17 .

09-25

The conf.py file has an error when there were no macros in the preamble.rst file. This has been fixed.

09-24

  1. Remove the xrst_before_title wish list item because it was completed.

  2. Add examples showing how to use group list option.

  3. Fix a problem with build the pdf target on sphinx 4.1.2, to be specific:

    ! LaTeX Error: Command \thesubpage undefined.

  4. There was a problem with the code_cmd when it was inside a list. This has been fixed and the corresponding Code Command in List example now displays properly. To be specific, its second item starts with 2 instead of 1.

  5. Remove the latex generated section numbers from the pdf output because xrst includes its own value for the section numbering.

09-23

  1. The error message when a file specified by a toc_cmd did not correctly state the command with the error. This has been fixed.

  2. Modify the wish list Tabs item. Add the xrst_before_title wish list item.

09-22

  1. The code command would not include the comment character in it’s displayed output. This has been fixed.

  2. An RST Directive was added to the list example. (This has been removed because it did not function properly.)

  3. All the pages were being included by the toc_cmd. This has been fixed; i.e., only child pages with the same group_name are included.

09-21

  1. Add the dev group to the xrst documentation. This group contains the developer documentation; see group_list .

  2. Change the comment_ch_cmd from file scope to page scope.

09-20

Change indent_example so that it is also a python docstring and add the docstring_example. The spell_example was moved from spell.py to spell.xrst because it does not have any python code in it.

09-19

If html_theme is sphinx_rtd_theme, modify the theme.css file so that the full width of display window is used and the navigation sidebar takes less space. (The navigation side bar does not need as much space when using xrst.)

09-18

  1. Fix the indentation when an xsrst code command in a list item and add an example that demonstrates this case; see Code Command in List .

  2. Add four new items to the wish_list (and edit the Tabs item).

09-17

Report an error when the underbar character _ is at the end of a heading (because Sphinx does not handle this case).

09-15

Put the dates in the release notes below the heading mm-dd . This makes the corresponding automatically generated links work better because they use the date instead of an id number that changes with each change to the release notes.

09-14

  1. Change the link to the title for a page from @ page_name to page_name -title ; see Level Zero heading links. This has the advantage that the html link uses the page name instead of an id number.

  2. Do not map characters (except for : and @ ) when automatically creating labels; see Heading@To@Label for heading links. This makes these labels work more link the automatic standard rst labels.

  3. There was a bug in the reported line number when a page_name was not valid. This has been fixed

09-13

There was a crash during the error message when the language was included in the {xrst_code} that terminated a code command. This has been fixed.

09-11

  1. Change comment_ch_example to be a matlab / octave input file example.

  2. The replace_spell_commands option did not work properly in files that contained a comment_ch_cmd. This has been fixed.

  3. The indent_cmd did not work properly in files that contained comment_ch_cmd. This has been fixed.

  4. The comment command was added; see comment_example.

  5. Add an error message when comment_ch_cmd is present but not used before the begin_cmd for a page.

  6. There was a bug when there was more then one code_cmd pair in a page. This has been fixed.

09-09

  1. There was a problem with the Child Links at the end of a page when there was no xrst toc command in the page. This has been fixed.

  2. The line numbers reported by error messages was wrong when a file began with a newline. This also caused the replace_spell_commands option to not work. These problems have been fixed.

09-08

There was a bug in the replace_spell_commands option when generating double words exceptions. This has been fixed.

09-05

The Table of Contents did not build properly unless |space| was defined in preamble.rst file. This has been fixed.

09-04

Change the location of the output html files so they are in the output_dir instead of its rst subdirectory.

09-02

  1. Change literal_cmd so that display file is always first (when it appears in the syntax).

  2. Exit with an error message when an heading underline is longer than the heading text above or when the overline is different from the underline.

08-31

Change copyright and license notice to use spdx .

08-30

Change ‘section’ to ‘page’ because section is used in sphinx to refer to text grouped by headings.

08-29

Add the replace_spell_commands option and remove the corresponding wish_list item.

08-27

Fix build when target is pdf. To be specific, do not include xrst_index.rst in index.rst.

08-24

  1. Allow headings to be just one character; e.g., x in the heading_example section. Also fix the displayed labels in that example section by changing . to @.

  2. When a character that is not a letter or white space appears in the spell_cmd world list, the error used to report the line number where the spell command started. Now it reports the line where the bad character occurs.

08-22

  1. Better detection and reporting of syntax errors in commands .

  2. Add sphinx_book_theme to the possible choices for html_theme.

  3. Remove the wish_list subset documentation item. It was completed on 08-05 when the group_list option was added.

  4. Change the standard for each level of indent from 4 to 3 spaces and remove the corresponding wish list item.

08-21

  1. Change the command names listed below; see toc_cmd and literal_cmd . This was done because the child commands act like sphinx toctree commands and the file command acts like a sphinx literalinclude command.

    xrst_file

    ->

    xrst_literal

    xrst_children

    ->

    xrst_toc_hidden

    xrst_child_list

    ->

    xrst_toc_list

    xrst_child_table

    ->

    xrst_toc_table

  2. Use the backslash in {xrst_ to escape xrst commands . In addition, remove the restriction that commands must occur at the beginning of a line. (The code_cmd never had this restriction.)

08-20

  1. Add the html_theme option to the xrst command line.

  2. Make some minor corrections to the documentation for labels under Level Zero and the first item under Discussion .

08-17

Change the xrst command Syntax to use more descriptive flags; e.g. -v was changed to --version.

08-15

  1. Add deprecated to the xrst dictionary.

  2. Extend keyword file to remove version number from index.

08-09

  1. The colon : was added to the characters that get changed to underbar _ when converting headings to labels. This has been change; see 11-15 .

  2. Sphinx warnings that occurred while running xrst were not being reported. This has been fixed.

  3. Two broken cross reference links (reported by sphinx warnings) were fixed.

08-08

  1. Fix documentation for relative location of display_file in literal command and File List in toc commands. This changed from where xrst is execute to where root_file is located on 07-30 .

  2. Improve the documentation index; for example, improve keyword file documentation.

08-07

  1. Add the version option which prints the version of xrst.

  2. Put project_name at top of html documentation.

08-06

  1. Automatically run sphinx after xrst has created the sphinx input file.

  2. Add the output_dir option to the command line.

  3. Add the No start or end syntax to the literal command.

08-05

  1. Add the group_list option to the command line.

  2. Use the base part of root_file as the sphinx project name.

08-04

Make target and sphinx_dir optional command line arguments with default values; see the new xrst Syntax.

08-03

The heading links at the Level Zero were changed to make it easier to display the section name as the linking text. You must change :ref: ` page_name ` to :ref: ` @ page_name ` to get the linking text to be the title (as it was before this change). The following can be used to convert file_name to this new convention:

bin/update_xrst.py ref_section file_name file_name

07-31

Move the hidden toctree commands in rst files from beginning to end of sections. This puts the parent sections before their children in the pdf version of the documentation (see target .

07-30

  1. Automatically create the file conf.py.

  2. Make all file names, except the root_file, relative to where the root file is located.

  3. The file names for preamble.rst, spelling, and keyword are no longer user selectable. These names have been removed from the xrst Syntax and the corresponding files are optional (no longer required).

07-28

  1. Change xsrst to xrst

  2. Create the first pip install of xrst.

07-27

Improve the specification of how the toc commands and begin_parent command interact; see Children.

07-26

  1. Change the heading level separator character from period . to at sign @; see links to headings Other Levels.

  2. Add period . to the list of valid characters in a page_name.

  3. Change the following section names in the xrst documentation: xrst_py -> xrst.py, conf_py -> conf.py.

07-25

  1. Require that the suspend and resume commands are in their own line; see Suspend and Resume Commands.

  2. A problem was fixed the table corresponding to the rst_line command line argument. To be specific, the indices in the rst file were one larger than they should have been. (This command line argument has been removed; see 11-13 .)

07-24

  1. Remove ignore spelling of latex commands from wish list (done).

  2. Add a standard indent, Relative File Names, and Git Repository entries to wish list. All of these items have been completed.

07-21

Ignore the spelling of all words that are preceded by a backslash (this ignores all latex commands); see Spell Command.