Attempts to create a new reStructuredText code example from a `code-block` or `sourcecode` directive. If one couldn't be found, then `None` is returned.
(original: InputDocstringLine<'src>)
| 1055 | /// `code-block` or `sourcecode` directive. If one couldn't be found, then |
| 1056 | /// `None` is returned. |
| 1057 | fn new_code_block(original: InputDocstringLine<'src>) -> Option<CodeExampleRst<'src>> { |
| 1058 | // This regex attempts to parse the start of a reStructuredText code |
| 1059 | // block [directive]. From the reStructuredText spec: |
| 1060 | // |
| 1061 | // > Directives are indicated by an explicit markup start (".. ") |
| 1062 | // > followed by the directive type, two colons, and whitespace |
| 1063 | // > (together called the "directive marker"). Directive types |
| 1064 | // > are case-insensitive single words (alphanumerics plus |
| 1065 | // > isolated internal hyphens, underscores, plus signs, colons, |
| 1066 | // > and periods; no whitespace). |
| 1067 | // |
| 1068 | // The language names matched here (e.g., `python` or `py`) are taken |
| 1069 | // from the [Pygments lexer names], which is referenced from the docs |
| 1070 | // for the [code-block] directive. |
| 1071 | // |
| 1072 | // [directives]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives |
| 1073 | // [Pygments lexer names]: https://pygments.org/docs/lexers/ |
| 1074 | // [code-block]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block |
| 1075 | static DIRECTIVE_START: LazyLock<Regex> = LazyLock::new(|| { |
| 1076 | Regex::new( |
| 1077 | r"(?m)^\s*\.\. \s*(?i:code-block|sourcecode)::\s*(?i:python|py|python3|py3)$", |
| 1078 | ) |
| 1079 | .unwrap() |
| 1080 | }); |
| 1081 | if !DIRECTIVE_START.is_match(original.line) { |
| 1082 | return None; |
| 1083 | } |
| 1084 | Some(CodeExampleRst { |
| 1085 | lines: vec![], |
| 1086 | opening_indent: Indentation::from_str(original.line), |
| 1087 | min_indent: None, |
| 1088 | is_directive: true, |
| 1089 | }) |
| 1090 | } |
| 1091 | |
| 1092 | /// Returns the code collected in this example as a sequence of lines. |
| 1093 | /// |