xrst - Man Page

xrst \
      [ --version ] \
      [ --local_toc ] \
      [ --page_source ] \
      [ --replace_spell_commands ] \
      [ --suppress_spell_warnings ] \
      [ --continue_with_warnings ] \
      [ --rst_line_numbers ] \
      [ --rst_only ] \
      [ --index_page_name index_page_name ] \
      [ --config_file     config_file ] \
      [ --html_theme      html_theme ] \
      [ --target          target ]  \
      [ --number_jobs     number_jobs ] \
      [ --group_list      group_name_1 group_name_2 ... ] \
      [ --rename_group    old_group_name new_group_name ] \

1. The brackets around each of lines above indicate that the line is optional.
2. The lines above can appear in any order.
3. Text in code font; e.g. --target is explicit; i.e., must appear exactly as above.
4. Text in italic font; .e.g, target is implicit; i.e., it gets replaced by the user's choice.
5. It may be helpful to remove the html_directory before running the command below. This will check for error messages that are not repeated due to caching the results of previous builds.

If --version is present on the command line, the version of xrst is printed and none of the other arguments matter.

If this option is present on the command line, a table of contents for the Headings in the current page is included at the top of every page. The page name and page title are not in this table of contents.

Some html themes include this information on a side bar; e.g., furo and sphinx_book_theme .

If this option is present and target is html , a link to the xrst source code is included at the top of each page. Some html themes include this link; e.g., sphinx_rtd_theme .

If this option is present and target is tex , the xrst source code file is reported at the beginning of each page.

If this option is present on the command line, the source code spell commands are replaced in such a way that the there will be no spelling warnings during future processing by xrst.

1. This is useful when there are no spelling warnings before a change to the project_dictionary or when there is an update to the spell_package .
2. This is also useful when there are no spelling warnings and you want to sort the words in all the spelling commands.
3. If this option is present, none of the output files are created; e.g., the *.rst and *.html files.

See also project_dictionary .

If this option is present on the command line, none of the spelling warnings will be generated. This is useful when there are no spelling warnings with one spelling package and you are temporarily using a different version of the package or a different package altogether.

If this option is (is not) present on the command line, the program will not exit (will exit) with an error when warnings are generated.

Normally sphinx error and warning messages are reported using line numbers in the xrst source code files. If this option is present, these messages are reported using the line numbers in the RST files created by xrst. In addition the page_source links to the rst files, instead of the xrst source files. This may be helpful if you have an error or warning for a sphinx command and it does not make sense using xrst source code line numbers. It is also helpful for determining if an incorrect line number is due to sphinx or xrst.

Normally, after extraction the RST files, xrst automatically runs sphinx to produce the target output (html or tex). If this option is present, sphinx is not run. Only the rst files, and their corresponding sources, are generated; i.e.,

      rst_directory/*.rst
      rst_directory/_sources/*.txt

This may be useful when creating rst files for uses else where; e.g., for use with Read the Docs (see .readthedocs.yaml for a better way to use Read the Docs.) The sphinx commands are printed after xrst finishes and can be executed by hand. This may be useful if there is a problem during these commands.

This option has no effect when target is tex . If target is html, the file index.html in the html_directory will be a redirect to the page specified by index_page_name . If this option is not present, index.html wil be a redirect to the root of the documentation tree.

The command line argument config_file specifies the location of the config_file for this project. This can be an absolute path or relative to the directory where xrst is run.

This the html_theme that is used. The default value for html_theme is furo .

The command line argument target must be html or tex. It specifies the type of type output you plan to generate using sphinx. Note thet html_directory and tex_directory will determine the location of the corresponding output files. The default value for target is html .

This is a positive integer specifying the number of parallel jobs that xrst is allowed to use. The default value for number_jobs is 1 .

It is possible to select one or more groups of pages to include in the output using this argument.

1. The group_list is a list of one or more group names.
2. The Default Group is represented by the group name default .
3. The order of the group names determines their order in the resulting output.
4. The default value for group_list is default .

For each group name in the group_list there must be an entry in root_file specifying the root file for that group name.

The xrst examples are a subset of its user documentation and its user documentation is a subset of its developer documentation. For each command, the same source code file provides both the user and developer documentation. In addition, the developer documentation has links to the user documentation and the user documentation has links to the examples.

If this option is present on the command line, the group_name in a subset of the source code, is changed. This option replaces the group_list by the list whose only entry is new_group_name . None of the output files are created when rename_group is present; e.g., the *.rst and *.html files.