reStructuredText test page

Heading 3

Interpreted text

Interpreted text (text surrounded by single `) is not intended for literal text but for domain- or application-specific meaning. So far there is only 1 use of interpretext text - custom code highlight (with explicit naming of the cch plugin). Search (unwanted) uses of interpreted text by grep -rn "[^\`:]\`[A-Za-z0-9_ ]\+\`[^_\`]" --include="*.rst" website/pages/ (the only results should be on the this test page).

Escaping

If you find that you want to use one of the "special" characters in text, it will generally be OK -- reStructuredText is pretty smart. For example, this lone asterisk * is handled just fine, as is the asterisk in this equation: 5*6=30. If you actually want text surrounded by asterisks to not be italicised, then you need to indicate that the asterisk is not special. You do this by placing a backslash just before it, like so "*". Inline markup by itself (surrounded by whitespace) or in the middle of a word won't be recognized - it has to be escaped like in the following sentence:

Possible in reStructuredText, though not encouraged.

Inline markup - HTML

Do not use HTML tags inside reStructuredText pages. reStructuredText exists with its features to avoid manually writing HTML (or other output-specific) markup. HTML in reStructuredText sources will be escaped and render <u>unformatted</u>.

References

Citations

Citation references, like [CIT2002]. Note that citations may get rearranged, e.g., to the bottom of the "page".

Citation labels contain alphanumerics, underlines, hyphens and fullstops. Case is not significant.

Given a citation like [this], one can also refer to it like this.

Hyperlink Targets

Substitution References and Definitions

Substitutions are like inline directives, allowing graphics and arbitrary constructs within text.

The symbol must be used on containers used to dispose of medical waste. And here is a fancy jumping ball: .

Implemented lists

Note that a blank line is required before the first item and after the last, but is optional between items.

Unsupported lists

Not recommended to use, not implemented and likely will not be needed:

• definition list

• field list

• option list

Grid table

Simple table

CSV Table

The "csv-table" directive is used to create a table from CSV (comma-separated values) data. CSV is a common data format generated by spreadsheet applications and commercial databases. The data may be internal (an integral part of the document) or external (a separate file).

Example:

Block markup and inline markup within cells is supported. Line ends are recognized within cells.

Working limitations:

• There is no support for checking that the number of columns in each row is the same. However, this directive supports CSV generators that do not insert "empty" entries at the end of short rows, by automatically adding empty entries.

• Whitespace delimiters are supported only for external CSV files.

• With Python 2, the valuess for the delimiter, quote, and escape options must be ASCII characters. (The csv module does not support Unicode and all non-ASCII characters are encoded as multi-byte utf-8 string). This limitation does not exist under Python 3.

The following options are recognized:

widthsinteger [, integer...] or "auto"

A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns).

The special value "auto" may be used by writers to decide whether to delegate the determination of column widths to the backend (LaTeX, the HTML browser, ...).

widthlength or percentage of the current line width

Forces the width of the table to the specified length or percentage of the line width. If omitted, the renderer determines the width of the table based on its contents.

header-rowsinteger

The number of rows of CSV data to use in the table header. Defaults to 0.

stub-columnsinteger

The number of table columns to use as stubs (row titles, on the left). Defaults to 0.

headerCSV data

Supplemental data for the table header, added independently of and before any header-rows from the main CSV data. Must use the same CSV format as the main CSV data.

filestring (newlines removed)

The local filesystem path to a CSV data file.

urlstring (whitespace removed)

An Internet URL reference to a CSV data file.

encodingname of text encoding

The text encoding of the external CSV data (file or URL). Defaults to the document's encoding (if specified).

delimchar | "tab" | "space"

A one-character string used to separate fields. Defaults to , (comma). May be specified as a Unicode code point; see the unicode directive for syntax details.

quotechar

A one-character string used to quote elements containing the delimiter or which start with the quote character. Defaults to " (quote). May be specified as a Unicode code point; see the unicode directive for syntax details.

keepspaceflag

Treat whitespace immediately following the delimiter as significant. The default is to ignore such whitespace.

escapechar

A one-character string used to escape the delimiter or quote characters. May be specified as a Unicode code point; see the unicode directive for syntax details. Used when the delimiter is used in an unquoted field, or when quote characters are used within a field. The default is to double-up the character, e.g. "He said, ""Hi!"""

align"left", "center", or "right"

The horizontal alignment of the table. (New in Docutils 0.13)

and the common options :class: and :name:.

List Table

The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist (second-level list) must contain the same number of list items.

The following options are recognized:

widthsinteger [integer...] or "auto"

A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns).

The special value "auto" may be used by writers to decide whether to delegate the determination of column widths to the backend (LaTeX, the HTML browser, ...).

widthlength or percentage of the current line width

Forces the width of the table to the specified length or percentage of the line width. If omitted, the renderer determines the width of the table based on its contents.

header-rowsinteger

The number of rows of list data to use in the table header. Defaults to 0.

stub-columnsinteger

The number of table columns to use as stubs (row titles, on the left). Defaults to 0.

align"left", "center", or "right"

The horizontal alignment of the table. (New in Docutils 0.13)

and the common options :class: and :name:.

Image

Inline images can be defined with an "image" directive in a substitution definition.

The URI for the image source file is specified in the directive argument. As with hyperlink targets, the image URI may begin on the same line as the explicit markup start and target name, or it may begin in an indented text block immediately following, with no intervening blank lines. If there are multiple lines in the link block, they are stripped of leading and trailing whitespace and joined together.

Optionally, the image link block may contain a flat field list, the image options.

Most useful options: alt and target (clickable image).

The following options are recognized:

alttext

Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users.

heightlength

The desired height of the image. Used to reserve space or scale the image vertically. When the "scale" option is also specified, they are combined. For example, a height of 200px and a scale of 50 is equivalent to a height of 100px with no scale.

widthlength or percentage of the current line width

The width of the image. Used to reserve space or scale the image horizontally. As with "height" above, when the "scale" option is also specified, they are combined.

scaleinteger percentage (the "%" symbol is optional)

The uniform scaling factor of the image. The default is "100%", i.e. no scaling.

If no "height" or "width" options are specified, the Python Imaging Library (PIL) may be used to determine them, if it is installed and the image file is available.

align"top", "middle", "bottom", "left", "center", or "right"

The alignment of the image, equivalent to the HTML <img> tag's deprecated "align" attribute or the corresponding "vertical-align" and "text-align" CSS properties. The values "top", "middle", and "bottom" control an image's vertical alignment (relative to the text baseline); they are only useful for inline images (substitutions). The values "left", "center", and "right" control an image's horizontal alignment, allowing the image to float and have the text flow around it. The specific behavior depends upon the browser or rendering software used.

targettext (URI or reference name)

Makes the image into a hyperlink reference ("clickable"). The option argument may be a URI (relative or absolute), or a reference name with underscore suffix (e.g. `a name`_).

and the common options :class: and :name:.

Figure

A "figure" consists of image data (including image options), an optional caption (a single paragraph), and an optional legend (arbitrary body elements). For page-based output media, figures might float to a different position if this helps the page layout.

Unicode Character Codes

The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only.

The arguments, separated by spaces, can be:

• character codes as

  • decimal numbers or

  • hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. ᨫ

• text, which is used as-is.

Text following " .. " is a comment and is ignored. The spaces between the arguments are ignored and thus do not appear in the output. Hexadecimal codes are case-insensitive.

For example:

Copyright © 2003, BogusMegaCorp™—all rights reserved.

Including an External Document Fragment

The "include" directive reads a text file. The directive argument is the path to the file to be included, relative to the document containing the directive. For example:

This first example will be parsed at the document level, and can
thus contain any construct, including section headers.

.. include:: inclusion.txt

Back in the main document.

This can be useful for articles/tutorials which share same/similar set of information. Nikola also supports root-relative include paths, which are preferred in this project.

Code

The "code" directive constructs a literal block. Language and number-lines options are optional. Currently there is no Pygments-based highlighting. The indent needs to be the same for directive options and directive content.

The code directive is used on the website but only for non-highlighted code like shell output of sample programs. Use custom directives for highlighted code.

Non-highlighted code sample:

/tmp/ccQJjzeS.o: In function `main':
main.cpp:(.text+0x5): undefined reference to `write_hello()'
collect2: error: ld returned 1 exit status

Details element

Creates spoiler-like element, using HTML <details> tag. Support through details_element plugin.

• Optional option: open (no arguments), causes the details element to be initially open (<details open>).

• Required option: summary, text to always display (<summary>)

Admonitions

There are some predefined admonitions but they do not allow to change the title text, which is a reason big enough to abandom them. Use only these custom admonitions:

Custom code highlight

Custom code highlight is implemented in rest_highlighter plugin. It offers 3 ways to generate highlighted code:

• interpreted text (inline markup, not a directive)

• mirror-based highlight (explicit semi-automatic colorization)

• Clangd-based highlight (compiler-backed automatic colorization)

and one extra feature:

• ANSI highlight (colorful terminal output)

For all directives, if paths begin with /, they are relative to the conf.py file, otherwise they are relative to the file containing the directive.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

#include <fmt>
#include <iomanip>
#include <iostream>
#include <string>
#include <type_traits>
#include <variant>
#include <vector>

#ifdef SOME_MACRO
#undef SOME_MACRO // macros are bad

template <typename T>
struct always_false : std::false_type {};

/** @brief alias for our variant */
using var_t = std::variant<int, long, double, std::string>;

template <typename... Ts>
struct overloaded : Ts... { using Ts::operator()...; };
template <typename... Ts>
overloaded(Ts...) -> overloaded<Ts...>;

template <typename T>
concept Opaque = requires(T x)
{
	{*x} -> typename T::inner; // the expression *x must be valid
	                           // AND the type T::inner must be valid
	                           // AND the result of *x must be convertible to T::inner
};

template <Callable C, typename... Args> constexpr
decltype(auto) execute(C&& func, Args&&... args) // constrained C++20 function template
{
	return std::forward<C>(func)(std::forward<Args>(args)...);
}

template <typename Tuple, std::size_t... Is> constexpr
bool are_sorted_impl(Tuple&& tuple, std::index_sequence<Is...>)
{
	return !((std::get<Is + 1>(std::forward<Tuple>(tuple)) < std::get<Is>(std::forward<Tuple>(tuple))) && ...);
}

template <LessThanComparable... Args> constexpr
bool are_sorted(Args&&... args)
{
	if constexpr (sizeof...(Args) <= 1u)
		return true;
	else /// @note else needed to discard template instantiation of index sequence with sizeof...(T) - 1 with [T = 0]
		return are_sorted_impl(std::forward_as_tuple(std::forward<Args>(args)...), std::make_index_sequence<sizeof...(Args) - 1>{});
}

int main()
{
	std::vector<var_t> vec = {10, 15l, 1.5, "hello"};

	for (auto& v : vec)
	{
		// void visitor, only called for side-effects
		std::visit([](auto&& arg) { std::cout << arg; }, v);

		// value-returning visitor; a common idiom is to return another variant
		v = std::visit([](auto&& arg) -> var_t { return arg + arg; }, v);

		std::cout << " after doubling is ";

		// type-matching visitor: can also be a class with 4 overloaded operator()s
		std::visit([](auto&& arg)
		{
			using T = std::decay_t<decltype(arg)>;

			if constexpr (std::is_same_v<T, int>)
				std::fmt::print("int with value {}\n", arg);
			else if constexpr (std::is_same_v<T, long>)
				std::fmt::print("long with value {}\n", arg);
			else if constexpr (std::is_same_v<T, double>)
				std::fmt::print("double with value {}\n", arg);
			else if constexpr (std::is_same_v<T, std::string>)
				std::fmt::print("std::string with value '{}'\n", arg);
			else
				static_assert(always_false<T>::value, "non-exhaustive visitor!");
		}, v);
	}

	for (const auto& v : vec)
	{
		std::visit(overloaded {
			[](auto arg) { std::cout << arg << ' '; },
			[](double arg) { std::cout << std::fixed << arg << ' '; },
			[](const std::string& arg) { std::cout << std::quoted(arg) << ' '; }
		}, v);
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

#include <iostream>
#include <utility>

#define EMPTY
#define PRINT(x) \
	std::cout << #x " = " << (x) << "\n"

#ifndef EMPTY
#define BUG
#error Misconfigured build!
#endif

// some comment
template <typename T>
struct test
{
	/**
	 * @brief reset an object of type T
	 * @param value the object
	 * @return void
	 */
	void reset(T& value) const noexcept(noexcept(T{}))
	{
		// TODO make a version with T()
		value = EMPTY T{};
	}

	template <typename U = T>
	decltype(auto) func(U&& object) const noexcept(noexcept(std::declval<U&&>().func()))
	{
		return std::forward<U>(object).func();
	}
};

[[nodiscard]] long long factorial(long long n)
{
	if (n < 2)
		return 1;
	else
		return n * factorial(n - 1);
}

#define X(g, ...)
auto global = /* not so multiline comment */ 123.456l;
# /// lone hash shouldn't be a problem

namespace anything { enum class something { one, two, three }; }

auto main() -> int
{
	test<decltype(global)>{}.reset(global);
	auto str_lit = R"test(raw\nstring\nliteral)test";
	PRINT(str_lit);
	const auto& fmt = L"pointer = %p, length = %zu, string = %s";
	std::cout << "sizeof(fmt) = " << sizeof(fmt) << "\n";
}

Custom ANSI highlight

Support through rest_highlighter plugin. Path is mandatory.

notes/working.md at the root of the repository describes how to generate text files with ANSI highlight from colorful terminal output.

In file included from /usr/include/c++/8/algorithm:62,
                 from main.cpp:1:
/usr/include/c++/8/bits/stl_algo.h: In instantiation of ‘void std::__sort(_RandomAccessIterator, _RandomAccessIterator, _Compare) [with _RandomAccessIterator = std::_List_iterator<int>; _Compare = __gnu_cxx::__ops::_Iter_less_iter]’:
/usr/include/c++/8/bits/stl_algo.h:4834:18:   required from ‘void std::sort(_RAIter, _RAIter) [with _RAIter = std::_List_iterator<int>]’
main.cpp:7:30:   required from here
/usr/include/c++/8/bits/stl_algo.h:1969:22: error: no match for ‘operator-’ (operand types are ‘std::_List_iterator<int>’ and ‘std::_List_iterator<int>’)
     std::__lg(__last - __first) * 2,
               ~~~~~~~^~~~~~~~~
In file included from /usr/include/c++/8/bits/stl_algobase.h:67,
                 from /usr/include/c++/8/algorithm:61,
                 from main.cpp:1:
/usr/include/c++/8/bits/stl_iterator.h:392:5: note: candidate: ‘template<class _IteratorL, class _IteratorR> constexpr decltype ((__y.base() - __x.base())) std::operator-(const std::reverse_iterator<_Iterator>&, const std::reverse_iterator<_IteratorR>&)’
     operator-(const reverse_iterator<_IteratorL>& __x,
     ^~~~~~~~
/usr/include/c++/8/bits/stl_iterator.h:392:5: note:   template argument deduction/substitution failed:
In file included from /usr/include/c++/8/algorithm:62,
                 from main.cpp:1:
/usr/include/c++/8/bits/stl_algo.h:1969:22: note:   ‘std::_List_iterator<int>’ is not derived from ‘const std::reverse_iterator<_Iterator>’
     std::__lg(__last - __first) * 2,
               ~~~~~~~^~~~~~~~~
In file included from /usr/include/c++/8/bits/stl_algobase.h:67,
                 from /usr/include/c++/8/algorithm:61,
                 from main.cpp:1:
/usr/include/c++/8/bits/stl_iterator.h:1188:5: note: candidate: ‘template<class _IteratorL, class _IteratorR> constexpr decltype ((__x.base() - __y.base())) std::operator-(const std::move_iterator<_IteratorL>&, const std::move_iterator<_IteratorR>&)’
     operator-(const move_iterator<_IteratorL>& __x,
     ^~~~~~~~
/usr/include/c++/8/bits/stl_iterator.h:1188:5: note:   template argument deduction/substitution failed:
In file included from /usr/include/c++/8/algorithm:62,
                 from main.cpp:1:
/usr/include/c++/8/bits/stl_algo.h:1969:22: note:   ‘std::_List_iterator<int>’ is not derived from ‘const std::move_iterator<_IteratorL>’
     std::__lg(__last - __first) * 2,
               ~~~~~~~^~~~~~~~~

main.cpp: In function ‘int func(int&)’:
main.cpp:7:1: warning: no return statement in function returning non-void [-Wreturn-type]
 }
 ^
main.cpp:3:15: warning: unused parameter ‘x’ [-Wunused-parameter]
 int func(int& x)
          ~~~~~^
main.cpp: In function ‘int main()’:
main.cpp:12:25: error: ‘x’ was not declared in this scope
  std::cout << "x = " << x << "\n";
                         ^
main.cpp:13:7: error: cannot bind non-const lvalue reference of type ‘int&’ to an rvalue of type ‘int’
  func(123);
       ^~~
main.cpp:3:5: note:   initializing argument 1 of ‘int func(int&)’
 int func(int& x)
     ^~~~