1RUN_XRST() RUN_XRST()
2
6 run_xrst - Run Extract Sphinx RST And Sphinx
7
9 It may be helpful to remove the html_directory before running the com‐
10 mand below. This will check for error messages that are not repeated
11 due to caching the results of previous builds.
12 xrst \
13 [ --version ] \
14 [ --local_toc ] \
15 [ --page_source ] \
16 [ --rst_line_numbers ] \
17 [ --rst_only ] \
18 [ --index_page_name index_page_name ] \
19 [ --config_file config_file ] \
20 [ --html_theme html_theme ] \
21 [ --target target ] \
22 [ --group_list group_name_1 group_name_2 ... ] \
23 [ --rename_group old_group_name new_group_name ] \
24 [ --replace_spell_commands ] \
25 [ --suppress_spell_warnings ] \
26
29 If --version is present on the command line, the version of xrst is
30 printed and none of the other arguments matter.
31
33 If this option is present on the command line, a table of contents for
34 the Headings in the current page is included at the top of every page.
35 The page name and page title are not in this table of contents.
36 Some html themes include this information on a side bar; e.g., furo and
38 sphinx_book_theme .
39
41 If this option is present and target is html , a link to the xrst
42 source code is included at the top of each page. Some html themes in‐
43 clude this link; e.g., sphinx_rtd_theme .
44 If this option is present and target is tex , the xrst source code file
46 is reported at the beginning of each page.
47
49 Normally sphinx error and warning messages are reported using line num‐
50 bers in the xrst source code files. If this option is present, these
51 messages are reported using the line numbers in the RST files created
52 by xrst. In addition the page_source links to the rst files, instead
53 of the xrst source files. This may be helpful if you have an error or
54 warning for a sphinx command and it does not make sense using xrst
55 source code line numbers. It is also helpful for determining if an in‐
56 correct line number is due to sphinx or xrst.
57
59 Normally, after extraction the RST files, xrst automatically runs
60 sphinx to produce the target output (html or tex). If this option is
61 present, sphinx not run. Only the rst files, and their corresponding
62 sources, are generated; i.e.,
63 rst_directory/*.rst
64 rst_directory/_sources/*.txt
65 This may be useful when creating rst files for uses else where; e.g.,
68 for use with Read the Docs . The sphinx commands are printed after
69 xrst finishes and can be executed by hand. This may be useful if there
70 is a problem during these commands.
71
73 This option has no effect when target is tex . If target is html, the
74 file index.html in the html_directory will be a redirect to the page
75 specified by index_page_name . If this option is not present, in‐
76 dex.html wil be a redirect to the root of the documentation tree.
77
79 The command line argument config_file specifies the location of the
80 config_file for this project. This can be an absolute path or relative
81 to the directory where xrst is run.
82 xrst.toml
84 If config_file is not present on the command line, the default value
85 xrst.toml is used for config_file .
86
88 This the html_theme that is used. The default value for html_theme is
89 furo .
90 Theme Choices
92 The following is a list of some themes that work well with the default
93 settings in html_theme_options . If you have a theme together with
94 html_theme_options that work well with xrst, please post an issue on
95 github so that it can be added to the list below.
96 Sphinx Themes
98 ┌────────────────────┬───────────┐
99 │name │ local_toc │
100 ├────────────────────┼───────────┤
101 │sphinx_rtd_theme │ yes │
102 ├────────────────────┼───────────┤
103 │furo │ no │
104 ├────────────────────┼───────────┤
105 │sphinx_book_theme │ no │
106 ├────────────────────┼───────────┤
107 │pydata_sphinx_theme │ no │
108 ├────────────────────┼───────────┤
109 │piccolo_theme │ no │
110 └────────────────────┴───────────┘
111 sphinx_rtd_theme
113 The sphinx_rtd theme builds faster than some of the other themes, so it
114 is suggested to use it for testing (with the --local_toc option). A
115 special modification is made to this theme when target is html, so that
116 it displays wider than its normal limit. This modification may be re‐
117 moved in the future.
118
120 The optional command line argument target must be html or tex. It
121 specifies the type of type output you plan to generate using sphinx.
122 Note thet html_directory and tex_directory will determine the location
123 of the corresponding output files. The default value for target is
124 html .
125 tex
127 If you choose this target, xrst will create the file project_name.tex
128 in the tex_directory . There are two reasons to build this file. One
129 is to create the file project_name.pdf which is a pdf version of the
130 documentation. The other is to test for errors in the latex sections
131 of the documentation. (MathJax displays latex errors in red, but one
132 has to check every page that has latex to find all the errors this
133 way.) Once you have built project_name.tex, the following command exe‐
134 cuted in project_directory will accomplish both purposes:
135 make -C tex_directory project_name.pdf
136 1. The project_name is specified in the configuration file.
138 2. The resulting output file will be project.pdf in the tex_directory .
140 3. If a Latex error is encountered, the pdf build will stop with a mes‐
142 sage at the ? prompt. If you enter q at this prompt, it will com‐
143 plete its processing in batch mode. You will be able to find the er‐
144 ror messages in the file project_name.log in the tex_directory .
145 4. Translating Latex errors to the corresponding xrst input file:
147 1. Latex error messages are reported using line numbers in the file
149 project.tex .
150 2. You may be able to find the corresponding xrst input file using
152 by using grep to find text that is near the error.
153 3. The page numbers in the xrst_table_of_contents are present in the
155 latex input (often near section*{ above the error) and may help
156 translate these line numbers to page names.
157 4. Given a page name, the corresponding xrst input file can be found
159 at the top of the html version of the page.
160
162 It is possible to select one or more groups of pages to include in the
163 output using this optional argument.
164 1. The group_list is a list of one or more group names.
166 2. The Default Group is represented by the group name default .
168 3. The order of the group names determines their order in the resulting
170 output.
171 4. The default value for group_list is default .
173 For each group name in the group_list there must be an entry in
175 root_file specifying the root file for that group name.
176 The xrst examples are a subset of its user documentation and its user
178 documentation is a subset of its developer documentation. For each
179 command, the same source code file provides both the user and developer
180 documentation. In addition, the developer documentation has links to
181 the user documentation and the user documentation has links to the ex‐
182 amples.
183 Example
185 The examples commands below assume you have cloned the xrst git reposi‐
186 tory and it is your current working directory.
187 1. The xrst examples use the default group and their documentation can
189 be built using
190 xrst --group_list default
191 2. The xrst user documentation uses the default and user groups and its
193 documentation can be built using
194 xrst --group_list default user
195 3. The xrst developer documentation uses the default, user, and dev
197 groups and its documentation can be built using
198 xrst --group_list default user dev
199
201 If this option is present on the command line, the group_name in a sub‐
202 set of the source code, is changed. This option replaces the
203 group_list by the list whose only entry is new_group_name . None of
204 the output files are created when rename_group is present; e.g., the
205 *.rst and *.html files.
206 old_group_name
208 is the old group name for the pages that will have their group name re‐
209 placed. Use default, instead of the empty group name, for the Default
210 Group .
211 new_group_name
213 Only the pages below the root_file for new_group_name are modified.
214 You can rename a subset of the old group by making the root file for
215 the new group different than the root file for the old group. Each
216 page in the old group, and below the root file for the new group, will
217 have its group name changed from old_group_name to new_group_name. Use
218 default, instead of the empty group name, for the Default Group .
219
221 If this option is present on the command line, the source code spell
222 commands are replaced in such a way that the there will be no spelling
223 warnings during future processing by xrst. This is useful when there
224 are no spelling warnings before a change to the project_dictionary or
225 when there is an update to the spell_package . If this option is
226 present, none of the output files are created; e.g., the *.rst and
227 *.html files.
228
230 If this option is present on the command line, none of the spelling
231 warnings will be printed. This is useful when there are no spelling
232 warnings with one spelling package and you are temporarily using a dif‐
233 ferent version of the package or a different package altogether.
234 RUN_XRST()