Given a code example, format them and return the formatted code as a sequence of owned docstring lines. This may mutate the code example in place if extracting the lines of code requires adjusting which part of each line is used for the actual code bit. This routine generally only returns an error when the recursive call to the formatter itself returns a `FormatError`. In all other cases (for ex
(
&mut self,
kind: &mut CodeExampleKind<'_>,
)
| 489 | /// fail silently. Ideally, this would at least emit a warning message, |
| 490 | /// but at time of writing, it wasn't clear to me how to best do that. |
| 491 | fn format( |
| 492 | &mut self, |
| 493 | kind: &mut CodeExampleKind<'_>, |
| 494 | ) -> FormatResult<Option<Vec<OutputDocstringLine<'static>>>> { |
| 495 | let line_width = match self.f.options().docstring_code_line_width() { |
| 496 | DocstringCodeLineWidth::Fixed(width) => width, |
| 497 | DocstringCodeLineWidth::Dynamic => { |
| 498 | let global_line_width = self.f.options().line_width().value(); |
| 499 | let indent_width = self.f.options().indent_width(); |
| 500 | let indent_level = self.f.context().indent_level(); |
| 501 | let mut current_indent = indent_level |
| 502 | .to_ascii_spaces(indent_width) |
| 503 | .saturating_add(kind.extra_indent_ascii_spaces()); |
| 504 | |
| 505 | // Add the in-docstring indentation |
| 506 | current_indent = current_indent.saturating_add( |
| 507 | u16::try_from( |
| 508 | kind.indent() |
| 509 | .columns() |
| 510 | .saturating_sub(self.stripped_indentation.columns()), |
| 511 | ) |
| 512 | .unwrap_or(u16::MAX), |
| 513 | ); |
| 514 | |
| 515 | let width = std::cmp::max(1, global_line_width.saturating_sub(current_indent)); |
| 516 | LineWidth::try_from(width).expect("width should be capped at a minimum of 1") |
| 517 | } |
| 518 | }; |
| 519 | |
| 520 | let code = kind.code(); |
| 521 | let (Some(unformatted_first), Some(unformatted_last)) = (code.first(), code.last()) else { |
| 522 | return Ok(None); |
| 523 | }; |
| 524 | let codeblob = code |
| 525 | .iter() |
| 526 | .map(|line| line.code) |
| 527 | .collect::<Vec<&str>>() |
| 528 | .join("\n"); |
| 529 | let options = self |
| 530 | .f |
| 531 | .options() |
| 532 | .clone() |
| 533 | .with_line_width(line_width) |
| 534 | // It's perhaps a little odd to be hard-coding the indent |
| 535 | // style here, but I believe it is necessary as a result |
| 536 | // of the whitespace normalization otherwise done in |
| 537 | // docstrings. Namely, tabs are rewritten with ASCII |
| 538 | // spaces. If code examples in docstrings are formatted |
| 539 | // with tabs and those tabs end up getting rewritten, this |
| 540 | // winds up screwing with the indentation in ways that |
| 541 | // results in formatting no longer being idempotent. Since |
| 542 | // tabs will get erased anyway, we just clobber them here |
| 543 | // instead of later, and as a result, get more consistent |
| 544 | // results. |
| 545 | .with_indent_style(IndentStyle::Space) |
| 546 | .with_source_map_generation(SourceMapGeneration::Disabled); |
| 547 | let printed = match docstring_format_source(options, self.quote_char, &codeblob) { |
| 548 | Ok(printed) => printed, |
no test coverage detected