README.html
1 <!DOCTYPE html> 2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 3 <head> 4 <meta charset="utf-8" /> 5 <meta name="generator" content="Docutils 0.20.1: https://docutils.sourceforge.io/" /> 6 <meta name="viewport" content="width=device-width, initial-scale=1" /> 7 <meta name="author" content="David Goodger" /> 8 <meta name="dcterms.date" content="2025-07-29" /> 9 <meta name="dcterms.rights" content="This document has been placed in the public domain." /> 10 <title>README: Docutils 0.23b.dev</title> 11 <link rel="schema.dcterms" href="http://purl.org/dc/terms/"/> 12 <style type="text/css"> 13 14 /* CSS3_ style sheet for the output of Docutils HTML5 writer. */ 15 /* Generic responsive design for all screen sizes. */ 16 /* */ 17 /* :Author: Günter Milde */ 18 /* */ 19 /* :Id: $Id: responsive.css 10170 2025-06-16 12:36:11Z milde $ */ 20 /* :Copyright: © 2021 Günter Milde. */ 21 /* :License: Released under the terms of the `2-Clause BSD license`_, */ 22 /* in short: */ 23 /* */ 24 /* Copying and distribution of this file, with or without modification, */ 25 /* are permitted in any medium without royalty provided the copyright */ 26 /* notice and this notice are preserved. */ 27 /* */ 28 /* This file is offered as-is, without any warranty. */ 29 /* */ 30 /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ 31 /* .. _CSS3: https://www.w3.org/Style/CSS/ */ 32 33 /* Note: */ 34 /* This style sheet is provisional: */ 35 /* the API is not settled and may change with any minor Docutils version. */ 36 37 38 39 /* General Settings */ 40 /* ================ */ 41 42 43 * { box-sizing: border-box; } 44 45 body { 46 background-color: #fafaf6; 47 margin: auto; 48 --field-indent: 6.6em; /* indent of fields in field lists */ 49 --sidebar-margin-right: 0; /* adapted in media queries below */ 50 } 51 main { 52 counter-reset: figure table; 53 } 54 body > * { 55 background-color: white; 56 line-height: 1.6; 57 padding: 0.5rem calc(29% - 7.2rem); /* go from 5% to 15% (8.15em/54em) */ 58 margin: auto; 59 max-width: 100rem; 60 } 61 sup, sub { /* avoid additional inter-line space for lines with sup/sub */ 62 line-height: 1; 63 } 64 65 /* Vertical Space (Parskip) */ 66 p, ol, ul, dl, li, 67 .topic, 68 .footnote, .citation, 69 div > math, 70 table { 71 margin-top: 0.5em; 72 margin-bottom: 0.5em; 73 } 74 h1, h2, h3, h4, h5, h6, 75 dl > dd, details > p:last-child { 76 margin-bottom: 0.5em; 77 } 78 79 /* Indented Blocks */ 80 blockquote, figure, .topic { 81 margin: 1em 2%; 82 padding-left: 1em; 83 } 84 div.line-block div.line-block, 85 pre, dd, dl.option-list { 86 margin-left: calc(2% + 1em); 87 } 88 89 /* Object styling */ 90 /* ============== */ 91 92 footer, header { 93 font-size: small; 94 } 95 96 /* Frontmatter */ 97 div.dedication { 98 padding: 0; 99 margin: 1.4em 0; 100 font-style: italic; 101 font-size: large; 102 } 103 .dedication p.topic-title { 104 display: none; 105 } 106 107 blockquote p.attribution { 108 text-align: right; 109 } 110 111 /* Table of Contents */ 112 nav.contents ul { 113 padding-left: 1em; 114 } 115 ul.auto-toc > li > p { /* hanging indent */ 116 padding-left: 1em; 117 text-indent: -1em; 118 } 119 main > nav.contents ul:not(.auto-toc) { 120 list-style-type: square; 121 } 122 main > nav.contents ul ul:not(.auto-toc) { 123 list-style-type: disc; 124 } 125 main > nav.contents ul ul ul:not(.auto-toc) { 126 list-style-type: '\2B29\ '; 127 } 128 main > nav.contents ul ul ul ul:not(.auto-toc) { 129 list-style-type: '\2B1D\ '; 130 } 131 main > nav.contents ul ul ul ul ul:not(.auto-toc) { 132 list-style-type: '\2B2A\ '; 133 } 134 nav.contents ul > li::marker { 135 color: grey; 136 } 137 138 /* Transitions */ 139 hr { 140 margin: 1em 10%; 141 } 142 143 /* Lists */ 144 145 dl.field-list.narrow { 146 --field-indent: 2.4em; 147 } 148 149 ul, ol { 150 padding-left: 1.1em; /* indent by bullet width (Firefox, DejaVu fonts) */ 151 } 152 dl.field-list > dd, 153 dl.docinfo > dd { 154 margin-left: var(--field-indent); /* adapted in media queries or HTML */ 155 } 156 dl.option-list > dd { 157 margin-left: 20%; 158 } 159 /* run-in: start field-body on same line after long field names */ 160 dl.field-list.run-in > dd p { 161 display: block; 162 } 163 /* "description style" like in most dictionaries, encyclopedias etc. */ 164 dl.description { 165 display: flow-root; 166 } 167 dl.description > dt { 168 clear: left; 169 float: left; 170 margin: 0; 171 padding: 0; 172 padding-right: 0.3em; 173 font-weight: bold; 174 } 175 dl.description > dd:after { 176 display: table; 177 content: ""; 178 clear: left; /* clearfix for empty descriptions */ 179 } 180 /* start lists nested in description/field lists on new line */ 181 dd > dl:first-child, 182 dd > ul:first-child, 183 dd > ol:first-child { 184 clear: left; 185 } 186 187 /* disclosures */ 188 details { padding-left: 1em; } 189 summary { margin-left: -1em; } 190 191 /* Footnotes and Citations */ 192 .footnote { 193 font-size: small; 194 } 195 196 /* Images, Figures, and Tables */ 197 figcaption, 198 table > caption { 199 /* font-size: small; */ 200 font-style: italic; 201 } 202 figcaption > .legend { 203 font-size: small; 204 font-style: initial; 205 } 206 figure.numbered > figcaption > p:before { 207 counter-increment: figure; 208 content: "Figure " counter(figure) ": "; 209 font-weight: bold; 210 font-style: initial; 211 } 212 213 table tr { 214 text-align: left; 215 vertical-align: baseline; 216 } 217 table.booktabs { /* "booktabs" style (no vertical lines) */ 218 border-top: 2px solid; 219 border-bottom: 2px solid; 220 } 221 table.booktabs * { 222 border: 0; 223 } 224 table.booktabs th { 225 border-bottom: thin solid; 226 } 227 table.numbered > caption:before { 228 counter-increment: table; 229 content: "Table " counter(table) ": "; 230 font-weight: bold; 231 font-style: initial; 232 } 233 234 /* Admonitions and System Messages */ 235 .admonition, 236 div.system-message { 237 border: thin solid silver; 238 margin: 1em 2%; 239 padding: 0.5em 1em; 240 } 241 .caution p.admonition-title, 242 .attention p.admonition-title, 243 .danger p.admonition-title, 244 .warning p.admonition-title, 245 div.error { 246 color: maroon; 247 } 248 div.system-message > p > span.literal { 249 overflow-wrap: break-word; 250 } 251 252 /* Literal and Code */ 253 pre.literal-block, pre.doctest{ 254 padding: 0.2em; 255 overflow-x: auto; 256 } 257 .literal-block, .doctest, span.literal { 258 background-color: #f0f5f3; 259 } 260 .system-message span.literal { 261 background-color: inherit; 262 } 263 264 /* basic highlighting: for a complete scheme, see */ 265 /* https://docutils.sourceforge.io/sandbox/stylesheets/ */ 266 pre.code .comment, code .comment { color: #5C6576 } 267 pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } 268 pre.code .literal.string, code .literal.string { color: #0C5404 } 269 pre.code .name.builtin, code .name.builtin { color: #352B84 } 270 pre.code .deleted, code .deleted { background-color: #DEB0A1} 271 pre.code .inserted, code .inserted { background-color: #A3D289} 272 273 /* Hyperlink References */ 274 a { 275 text-decoration: none; /* for chromium */ 276 /* Wrap links at any place, if this is the only way to prevent overflow */ 277 overflow-wrap: break-word; 278 } 279 .contents a, a.toc-backref, a.citation-reference { 280 overflow-wrap: inherit; 281 } 282 /* Undecorated Links (see also minimal.css) */ 283 /* a.citation-reference, */ 284 .citation a.fn-backref { 285 color: inherit; 286 } 287 a:hover { 288 text-decoration: underline; 289 } 290 *:hover > a.toc-backref:after, 291 .topic-title:hover > a:after { 292 content: " \2191"; /* ↑ UPWARDS ARROW */ 293 color: grey; 294 } 295 *:hover > a.self-link:after { 296 content: "\1F517"; /* LINK SYMBOL */ 297 color: grey; 298 font-size: smaller; 299 margin-left: 0.2em; 300 } 301 /* highlight specific targets of the current URL */ 302 section:target > h2, section:target > h3, section:target > h4, 303 section:target > h5, section:target > h6, 304 span:target + h2, span:target + h3, span:target + h4, 305 span:target + h5, span:target + h6, 306 dt:target, span:target, p:target, 307 .contents :target, 308 .contents:target > .topic-title, 309 aside.system-message:target, 310 [role="doc-biblioentry"]:target, 311 [role="doc-biblioref"]:target, 312 [role="note"]:target, /* Docutils 0.18 and 0.19 */ 313 [role="doc-footnote"]:target, /* Docutils >= 0.20 */ 314 [role="doc-noteref"]:target { 315 background-color: #d2e6ec; 316 } 317 318 /* Block Alignment */ 319 /* Let content flow to the side of aligned images and figures */ 320 321 /* no floats around this elements */ 322 footer, header, hr, 323 h1, h2, h3 { 324 clear: both; 325 } 326 327 img.align-left, 328 svg.align-left, 329 video.align-left, 330 figure.align-left, 331 div.align-left, 332 table.align-left { 333 margin-left: 0; 334 padding-left: 0; 335 margin-right: 0.5em; 336 clear: left; 337 float: left; 338 } 339 img.align-right, 340 svg.align-right, 341 video.align-right, 342 figure.align-right, 343 div.align-right, 344 table.align-right { 345 margin-left: 0.5em; 346 margin-right: 0; 347 clear: right; 348 float: right; 349 } 350 351 /* Margin Elements */ 352 /* see below for screen size dependent rules */ 353 .sidebar, 354 .marginal, 355 .admonition.marginal { 356 max-width: 40%; 357 border: none; 358 background-color: #efefea; 359 margin: 0.5em var(--sidebar-margin-right) 0.5em 1em; 360 padding: 0.5em; 361 padding-left: 0.7em; 362 clear: right; 363 float: right; 364 font-size: small; 365 } 366 .sidebar { 367 width: 40%; 368 } 369 370 /* Adaptive page layout */ 371 /* ==================== */ 372 373 @media (max-width: 30em) { 374 /* Smaller margins and no floating elements for small screens */ 375 /* (main text less than 40 characters/line) */ 376 body > * { 377 padding: 0.5rem 5%; 378 line-height: 1.4 379 } 380 .sidebar, 381 .marginal, 382 .admonition.marginal { 383 width: auto; 384 max-width: 100%; 385 float: none; 386 } 387 dl.option-list, 388 pre { 389 margin-left: 0; 390 } 391 body { 392 --field-indent: 4em; 393 } 394 dl.docinfo { 395 --field-indent: 5%; 396 } 397 pre, pre * { 398 font-size: 0.9em; 399 /* overflow: auto; */ 400 } 401 } 402 403 @media (min-width: 54em) { 404 /* Move ToC to the left */ 405 /* Main text width before: 70% ≙ 35em ≙ 75…95 chrs (Dejavu/Times) */ 406 /* after: ≳ 30em ≙ 54…70 chrs (Dejavu/Times) */ 407 body.with-toc { 408 padding-left: 8%; 409 } 410 body.with-toc > * { 411 margin-left: 0; 412 padding-left: 22rem; /* fallback for webkit */ 413 padding-left: min(22%, 22rem); 414 padding-right: 7%; 415 } 416 main > nav.contents { /* global ToC */ 417 position: fixed; 418 top: 0; 419 left: 0; 420 width: min(25%, 25em); 421 height: 100vh; 422 margin: 0; 423 background-color: #fafaf6; 424 padding: 1em 2% 0 2%; 425 overflow: auto; 426 } 427 main > nav.contents > * { 428 padding-left: 0; 429 line-height: 1.4; 430 } 431 main > nav.contents a { 432 color: inherit; 433 } 434 } 435 436 @media (min-width: 70em) { 437 body { 438 --field-indent: 9em; 439 } 440 } 441 442 @media (min-width: 77em) { 443 /* Move marginalia to 6rem from right border */ 444 /* .sidebar, */ 445 /* .marginal, */ 446 /* .admonition.marginal { */ 447 /* margin-right: calc(6rem - 15%); */ 448 /* } */ 449 /* BUG: margin is calculated for break point width */ 450 /* workaround: variable + many breakpoints */ 451 body > * { 452 padding-left: 18%; 453 padding-right: 28%; /* fallback for webkit */ 454 padding-right: min(28%, 28rem); 455 --sidebar-margin-right: -20rem; 456 } 457 /* limit main text to ~ 50em ≙ 85…100 characters DejaVu rsp. …120 Times */ 458 body.with-toc > * { 459 padding-left: min(22%, 22rem); 460 padding-right: calc(78% - 50rem); /* fallback for webkit */ 461 padding-right: min(78% - 50rem, 28rem); 462 --sidebar-margin-right: 0; 463 } 464 } 465 466 @media (min-width: 85em) { 467 body.with-toc > * { 468 --sidebar-margin-right: -9rem; 469 } 470 } 471 472 @media (min-width: 90em) { 473 /* move marginalia into the margin */ 474 body > * { 475 padding-left: min(22%, 22rem); 476 --sidebar-margin-right: -23rem; 477 } 478 body.with-toc > * { 479 --sidebar-margin-right: -14rem; 480 } 481 } 482 483 @media (min-width: 99em) { 484 /* move marginalia out of main text area */ 485 body.with-toc > * { 486 --sidebar-margin-right: -20rem; 487 } 488 body > *, body.with-toc > * { /* for webkit */ 489 padding-left: 22rem; 490 padding-right: 28rem; 491 } 492 .admonition.marginal, 493 .marginal { 494 width: 40%; /* make marginal figures, ... "full width" */ 495 } 496 } 497 498 @media (min-width: 104em) { 499 body.with-toc > * { 500 --sidebar-margin-right: -23rem; 501 } 502 } 503 504 </style> 505 <style type="text/css"> 506 507 /* Minimal style sheet for the HTML output of Docutils. */ 508 /* */ 509 /* :Author: Günter Milde, based on html4css1.css by David Goodger */ 510 /* :Id: $Id: minimal.css 10018 2025-03-06 16:19:15Z milde $ */ 511 /* :Copyright: © 2015, 2021 Günter Milde. */ 512 /* :License: Released under the terms of the `2-Clause BSD license`_, */ 513 /* in short: */ 514 /* */ 515 /* Copying and distribution of this file, with or without modification, */ 516 /* are permitted in any medium without royalty provided the copyright */ 517 /* notice and this notice are preserved. */ 518 /* */ 519 /* This file is offered as-is, without any warranty. */ 520 /* */ 521 /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ 522 523 /* This CSS3 stylesheet defines rules for Docutils elements without */ 524 /* HTML equivalent. It is required to make the document semantics visible. */ 525 /* */ 526 /* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */ 527 528 /* titles */ 529 p.topic-title, 530 p.admonition-title, 531 p.system-message-title { 532 font-weight: bold; 533 } 534 p.sidebar-title, 535 p.rubric { 536 font-weight: bold; 537 font-size: larger; 538 } 539 p.rubric { 540 color: maroon; 541 } 542 p.subtitle, 543 p.section-subtitle, 544 p.sidebar-subtitle { 545 font-weight: bold; 546 margin-top: -0.5em; 547 } 548 h1 + p.subtitle { 549 font-size: 1.6em; 550 } 551 a.toc-backref { 552 color: inherit; 553 text-decoration: none; 554 } 555 556 /* Warnings, Errors */ 557 .system-messages h2, 558 .system-message-title, 559 pre.problematic, 560 span.problematic { 561 color: red; 562 } 563 564 /* Inline Literals */ 565 .docutils.literal { 566 font-family: monospace; 567 white-space: pre-wrap; 568 } 569 /* do not wrap at hyphens and similar: */ 570 .literal > span.pre { white-space: nowrap; } 571 572 /* keep line-breaks (\n) visible */ 573 .pre-wrap { white-space: pre-wrap; } 574 575 /* Lists */ 576 577 /* compact and simple lists: no margin between items */ 578 .simple li, .simple ul, .simple ol, .simple > li p, 579 .compact li, .compact ul, .compact ol, .compact > li p, 580 dl.simple > dd, dl.compact > dd, dl.docinfo > dd { 581 margin-top: 0; 582 margin-bottom: 0; 583 } 584 /* Nested Paragraphs */ 585 p:first-child { margin-top: 0; } 586 p:last-child { margin-bottom: 0; } 587 details > p:last-child { margin-bottom: 1em; } 588 589 /* Table of Contents */ 590 .contents ul.auto-toc { /* section numbers present */ 591 list-style-type: none; 592 } 593 594 /* Enumerated Lists */ 595 ol.arabic { list-style: decimal } 596 ol.loweralpha { list-style: lower-alpha } 597 ol.upperalpha { list-style: upper-alpha } 598 ol.lowerroman { list-style: lower-roman } 599 ol.upperroman { list-style: upper-roman } 600 601 /* Definition Lists and Derivatives */ 602 dt .classifier { font-style: italic } 603 dt .classifier:before { 604 font-style: normal; 605 margin: 0.5em; 606 content: ":"; 607 } 608 /* Field Lists and similar */ 609 /* bold field name, content starts on the same line */ 610 dl.field-list, 611 dl.option-list, 612 dl.docinfo { 613 display: flow-root; 614 } 615 dl.field-list > dt, 616 dl.option-list > dt, 617 dl.docinfo > dt { 618 font-weight: bold; 619 clear: left; 620 float: left; 621 margin: 0; 622 padding: 0; 623 padding-right: 0.25em; 624 } 625 /* Offset for field content (corresponds to the --field-name-limit option) */ 626 dl.field-list > dd, 627 dl.option-list > dd, 628 dl.docinfo > dd { 629 margin-left: 9em; /* ca. 14 chars in the test examples, fit all Docinfo fields */ 630 } 631 /* start nested lists on new line */ 632 dd > dl:first-child, 633 dd > ul:first-child, 634 dd > ol:first-child { 635 clear: left; 636 } 637 /* start field-body on a new line after long field names */ 638 dl.field-list > dd > *:first-child, 639 dl.option-list > dd > *:first-child 640 { 641 display: inline-block; 642 width: 100%; 643 margin: 0; 644 } 645 646 /* Bibliographic Fields (docinfo) */ 647 dl.docinfo pre.address { 648 font: inherit; 649 margin: 0; 650 } 651 dl.docinfo > dd.authors > p { margin: 0; } 652 653 /* Option Lists */ 654 dl.option-list > dt { font-weight: normal; } 655 span.option { white-space: nowrap; } 656 657 /* Footnotes and Citations */ 658 659 .footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */ 660 /* hanging indent */ 661 .citation { padding-left: 2em; } 662 .footnote { padding-left: 1.7em; } 663 .footnote.superscript { padding-left: 1.0em; } 664 .citation > .label { margin-left: -2em; } 665 .footnote > .label { margin-left: -1.7em; } 666 .footnote.superscript > .label { margin-left: -1.0em; } 667 668 .footnote > .label + *, 669 .citation > .label + * { 670 display: inline-block; 671 margin-top: 0; 672 vertical-align: top; 673 } 674 .footnote > .backrefs + *, 675 .citation > .backrefs + * { 676 margin-top: 0; 677 } 678 .footnote > .label + p, .footnote > .backrefs + p, 679 .citation > .label + p, .citation > .backrefs + p { 680 display: inline; 681 vertical-align: inherit; 682 } 683 684 .backrefs { user-select: none; } 685 .backrefs > a { font-style: italic; } 686 687 /* superscript footnotes */ 688 a[role="doc-noteref"].superscript, 689 .footnote.superscript > .label, 690 .footnote.superscript > .backrefs { 691 vertical-align: super; 692 font-size: smaller; 693 line-height: 1; 694 } 695 a[role="doc-noteref"].superscript > .fn-bracket, 696 .footnote.superscript > .label > .fn-bracket { 697 /* hide brackets in display but leave for copy/paste */ 698 display: inline-block; 699 width: 0; 700 overflow: hidden; 701 } 702 [role="doc-noteref"].superscript + [role="doc-noteref"].superscript { 703 padding-left: 0.15em; /* separate consecutive footnote references */ 704 /* TODO: unfortunately, "+" also selects with text between the references. */ 705 } 706 707 /* Alignment */ 708 .align-left { 709 text-align: left; 710 margin-right: auto; 711 } 712 .align-center { 713 text-align: center; 714 margin-left: auto; 715 margin-right: auto; 716 } 717 .align-right { 718 text-align: right; 719 margin-left: auto; 720 } 721 .align-top { vertical-align: top; } 722 .align-middle { vertical-align: middle; } 723 .align-bottom { vertical-align: bottom; } 724 725 /* reset inner alignment in figures and tables */ 726 figure.align-left, figure.align-right, 727 table.align-left, table.align-center, table.align-right { 728 text-align: inherit; 729 } 730 731 /* Text Blocks */ 732 .topic { margin: 1em 2em; } 733 .sidebar, 734 .admonition, 735 .system-message { 736 margin: 1em 2em; 737 border: thin solid; 738 padding: 0.5em 1em; 739 } 740 div.line-block { display: block; } 741 div.line-block div.line-block, pre { margin-left: 2em; } 742 743 /* Code line numbers: don't copy with drag-and-drop */ 744 pre.code .ln { display: none; } 745 pre.code code:before { 746 content: attr(data-lineno); 747 font-size: small; 748 color: gray; 749 } 750 751 /* Tables */ 752 table { 753 border-collapse: collapse; 754 } 755 td, th { 756 border: thin solid silver; 757 padding: 0 1ex; 758 } 759 .borderless td, .borderless th { 760 border: 0; 761 padding: 0; 762 padding-right: 0.5em /* separate table cells */ 763 } 764 765 table > caption, figcaption { 766 text-align: left; 767 margin-top: 0.2em; 768 margin-bottom: 0.2em; 769 } 770 table.captionbelow { 771 caption-side: bottom; 772 } 773 774 /* MathML (see "math.css" for --math-output=HTML) */ 775 math .boldsymbol { font-weight: bold; } 776 math.boxed, math .boxed {padding: 0.25em; border: thin solid; } 777 /* style table similar to AMS "align" or "aligned" environment: */ 778 mtable.cases > mtr > mtd { text-align: left; } 779 mtable.ams-align > mtr > mtd { padding-left: 0; padding-right: 0; } 780 mtable.ams-align > mtr > mtd:nth-child(2n) { text-align: left; } 781 mtable.ams-align > mtr > mtd:nth-child(2n+1) { text-align: right; } 782 mtable.ams-align > mtr > mtd:nth-child(2n+3) { padding-left: 2em; } 783 .mathscr mi, mi.mathscr { 784 font-family: STIX, XITSMathJax_Script, rsfs10, 785 "Asana Math", Garamond, cursive; 786 } 787 788 /* Document Header and Footer */ 789 header { border-bottom: 1px solid black; } 790 footer { border-top: 1px solid black; } 791 792 /* Images are block-level by default in Docutils */ 793 /* New HTML5 block elements: set display for older browsers */ 794 img, svg, header, footer, main, aside, nav, section, figure, video, details { 795 display: block; 796 } 797 svg { width: auto; height: auto; } /* enable scaling of SVG images */ 798 /* inline images */ 799 800 p img, p svg, p video, 801 h1 img, h2 img, h3 img, h4 img, h5 img, h6 img, 802 h1 svg, h2 svg, h3 svg, h4 svg, h5 svg, h6 svg { 803 display: inline; 804 } 805 806 </style> 807 <style type="text/css"> 808 809 /* italic-field-name.css: */ 810 /* Alternative style for Docutils field-lists */ 811 812 /* :Copyright: © 2023 Günter Milde. */ 813 /* :License: Released under the terms of the `2-Clause BSD license`_, */ 814 /* in short: */ 815 /* */ 816 /* Copying and distribution of this file, with or without modification, */ 817 /* are permitted in any medium without royalty provided the copyright */ 818 /* notice and this notice are preserved. */ 819 /* */ 820 /* This file is offered as-is, without any warranty. */ 821 /* */ 822 /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ 823 824 /* In many contexts, a **bold** field name is too heavy styling. */ 825 /* Use *italic* instead:: */ 826 827 dl.field-list > dt { 828 font-weight: normal; 829 font-style: italic; 830 } 831 dl.field-list > dt > .colon { 832 font-style: normal; 833 padding-left: 0.05ex; 834 } 835 836 </style> 837 </head> 838 <body class="with-toc"> 839 <main id="readme-docutils-0-23b-dev"> 840 <h1 class="title">README: Docutils 0.23b.dev</h1> 841 <dl class="docinfo"> 842 <dt class="author">Author<span class="colon">:</span></dt> 843 <dd class="author"><p>David Goodger</p></dd> 844 <dt class="contact">Contact<span class="colon">:</span></dt> 845 <dd class="contact"><a class="reference external" href="mailto:goodger@python.org">goodger@python.org</a></dd> 846 <dt class="date">Date<span class="colon">:</span></dt> 847 <dd class="date">2025-07-29</dd> 848 <dt class="web-site">Web site<span class="colon">:</span></dt> 849 <dd class="web-site"><p><a class="reference external" href="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</a></p> 850 </dd> 851 <dt class="copyright">Copyright<span class="colon">:</span></dt> 852 <dd class="copyright">This document has been placed in the public domain.</dd> 853 </dl> 854 <div class="topic abstract" role="doc-abstract"> 855 <p class="topic-title">Abstract</p> 856 <p>Docutils is a modular system for processing documentation into 857 useful formats, such as HTML, XML, and LaTeX. 858 For input Docutils supports reStructuredText, an easy-to-read, 859 what-you-see-is-what-you-get plaintext markup syntax.</p> 860 </div> 861 <nav class="contents" id="contents" role="doc-toc"> 862 <p class="topic-title">Contents</p> 863 <ul class="simple"> 864 <li><p><a class="reference internal" href="#quick-start" id="toc-entry-1">Quick-Start</a></p></li> 865 <li><p><a class="reference internal" href="#purpose" id="toc-entry-2">Purpose</a></p></li> 866 <li><p><a class="reference internal" href="#dependencies" id="toc-entry-3">Dependencies</a></p> 867 <ul> 868 <li><p><a class="reference internal" href="#recommendations" id="toc-entry-4">Recommendations</a></p></li> 869 </ul> 870 </li> 871 <li><p><a class="reference internal" href="#installation" id="toc-entry-5">Installation</a></p> 872 <ul> 873 <li><p><a class="reference internal" href="#gnu-linux-bsds-unix-mac-os-x-etc" id="toc-entry-6">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a></p></li> 874 <li><p><a class="reference internal" href="#windows" id="toc-entry-7">Windows</a></p></li> 875 </ul> 876 </li> 877 <li><p><a class="reference internal" href="#usage" id="toc-entry-8">Usage</a></p></li> 878 <li><p><a class="reference internal" href="#project-files-directories" id="toc-entry-9">Project Files & Directories</a></p></li> 879 <li><p><a class="reference internal" href="#development-version" id="toc-entry-10">Development version</a></p></li> 880 <li><p><a class="reference internal" href="#converting-the-documentation" id="toc-entry-11">Converting the documentation</a></p></li> 881 <li><p><a class="reference internal" href="#running-the-test-suite" id="toc-entry-12">Running the Test Suite</a></p></li> 882 <li><p><a class="reference internal" href="#getting-help" id="toc-entry-13">Getting Help</a></p></li> 883 </ul> 884 </nav> 885 <section id="quick-start"> 886 <h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Quick-Start</a></h2> 887 <p>This is for those who want to get up & running quickly.</p> 888 <ol class="arabic"> 889 <li><p>Docutils requires <strong>Python</strong>, available from 890 <a class="reference external" href="https://www.python.org/">https://www.python.org/</a>. 891 See <a class="reference internal" href="#dependencies">Dependencies</a> below for details.</p></li> 892 <li><p>Install the latest stable release from PyPi with <a class="reference external" href="https://pypi.org/project/pip/">pip</a>:</p> 893 <pre class="literal-block">pip install docutils</pre> 894 <p>For alternatives and details, see section <a class="reference internal" href="#installation">Installation</a> below.</p> 895 </li> 896 <li><p>Use the <a class="reference external" href="docs/user/tools.html">front-end scripts</a> to convert reStructuredText documents. 897 Try for example:</p> 898 <pre class="literal-block">docutils FAQ.rst FAQ.html</pre> 899 <p>See <a class="reference internal" href="#usage">Usage</a> below for details.</p> 900 </li> 901 </ol> 902 </section> 903 <section id="purpose"> 904 <h2><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Purpose</a></h2> 905 <p>The purpose of the Docutils project is to provide a set of tools for 906 processing plaintext documentation into useful formats, such as HTML, 907 LaTeX, troff (man pages), OpenOffice, and native XML. Support for the 908 following sources has been implemented:</p> 909 <ul class="simple"> 910 <li><p>Standalone files.</p></li> 911 <li><p><a class="reference external" href="https://peps.python.org/pep-0012">PEPs (Python Enhancement Proposals)</a>.</p></li> 912 </ul> 913 <p>Support for the following sources is planned or provided by 914 <a class="reference external" href="docs/user/links.html#related-applications">third party tools</a>:</p> 915 <ul class="simple"> 916 <li><p>Inline documentation from Python modules and packages, extracted 917 with namespace context.</p></li> 918 <li><p>Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).</p></li> 919 <li><p>Wikis, with global reference lookups of "wiki links".</p></li> 920 <li><p>Compound documents, such as multiple chapter files merged into a 921 book.</p></li> 922 <li><p>And others as discovered.</p></li> 923 </ul> 924 </section> 925 <section id="dependencies"> 926 <h2><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">Dependencies</a></h2> 927 <p>To run the code, <a class="reference external" href="https://www.python.org/.">Python</a> must be installed. 928 (Python is pre-installed with most Linux distributions.)</p> 929 <ul class="simple"> 930 <li><p>Since version 0.21, Docutils requires Python 3.9 or later.</p></li> 931 <li><p>Docutils versions 0.19 to 0.20.1 require Python 3.7 or later.</p></li> 932 <li><p>Docutils versions 0.16 to 0.18 require Python 2.7 or 3.5+.</p></li> 933 </ul> 934 <p>The <strong>type hints</strong> added in version 0.22 use Python 3.10 syntax. 935 However, the Python interpreter treats them as annotations 936 unless <span class="docutils literal">typing.TYPE_CHECKING</span> is set to <span class="docutils literal">True</span>.</p> 937 <section id="recommendations"> 938 <h3><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Recommendations</a></h3> 939 <p>Docutils uses the following packages for enhanced functionality, if they 940 are installed:</p> 941 <ul class="simple"> 942 <li><p>The recommended installer is <a class="reference external" href="https://pypi.org/project/pip/">pip</a>, <a class="reference external" href="https://pypi.org/project/setuptools/">setuptools</a> works, too.</p></li> 943 <li><p>The <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a> (PIL) is used for some image 944 manipulation operations.</p></li> 945 <li><p>The <a class="reference external" href="https://pypi.org/project/Pygments/">Pygments</a> package provides syntax highlight of "code" directives 946 and roles.</p></li> 947 <li><p>The <a class="reference external" href="https://pypi.org/project/myst-docutils/">myst</a>, <a class="reference external" href="https://pypi.org/project/pycmark/">pycmark</a>, or <a class="reference external" href="https://github.com/rtfd/recommonmark">recommonmark</a> parsers can be used to 948 parse input in "Markdown" (<a class="reference external" href="https://spec.commonmark.org/0.30/">CommonMark</a>) format.</p></li> 949 </ul> 950 <p>The <a class="reference external" href="docs/user/links.html">Docutils Link List</a> records projects that 951 users of Docutils and reStructuredText may find useful.</p> 952 </section> 953 </section> 954 <section id="installation"> 955 <h2><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">Installation</a></h2> 956 <p>The <a class="reference external" href="https://packaging.python.org/en/latest/">Python Packaging User Guide</a> gives details how to 957 <a class="reference external" href="https://packaging.python.org/en/latest/tutorials/installing-packages/#use-pip-for-installing">use pip for installing</a>.</p> 958 <ul> 959 <li><p>The simplest way is to install the latest <em>stable release</em> from PyPi:</p> 960 <pre class="literal-block">pip install docutils</pre> 961 </li> 962 <li><p>To install a <em>pre-relase</em>, append the option <span class="docutils literal"><span class="pre">--pre</span></span>.</p></li> 963 <li><p>To install a <a class="reference internal" href="#development-version">development version</a> <em>from source</em>:</p> 964 <ol class="arabic"> 965 <li><p>Open a shell</p></li> 966 <li><p>Go to the directory containing the <span class="docutils literal">pyproject.toml</span> file.</p></li> 967 <li><p>Install the package with <strong>one</strong> of the following commands:</p> 968 <pre class="literal-block">pip install -e . # editable install 969 pip install . # regular install</pre> 970 <p>or do a <a class="reference external" href="docs/dev/repository.html#manual-install">"manual" install</a>.</p> 971 </li> 972 <li><p>Optional steps:</p> 973 <ul class="simple"> 974 <li><p><a class="reference internal" href="#running-the-test-suite">Running the test suite</a></p></li> 975 <li><p><a class="reference internal" href="#converting-the-documentation">Converting the documentation</a></p></li> 976 </ul> 977 </li> 978 </ol> 979 <p>See also the OS-specific installation instructions below and 980 the <a class="reference external" href="docs/dev/repository.html">Docutils version repository</a> documentation.</p> 981 </li> 982 <li><p>To install for a <em>specific Python version</em>, use this version in the 983 setup call, e.g.</p> 984 <pre class="literal-block">python3.11 -m pip install docutils</pre> 985 <p>If the python executable isn't on your path, you'll have to specify the 986 complete path, such as <span class="docutils literal">/usr/local/bin/python3.11</span>.</p> 987 <p>To install for different Python versions, repeat step 3 for every 988 required version. The last installed version will be used for the 989 <span class="docutils literal">docutils</span> command line application.</p> 990 </li> 991 </ul> 992 <section id="gnu-linux-bsds-unix-mac-os-x-etc"> 993 <h3><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">GNU/Linux, BSDs, Unix, Mac OS X, etc.</a></h3> 994 <ul> 995 <li><p>Use <span class="docutils literal">su</span> or <span class="docutils literal">sudo</span> for a system-wide 996 installation as <span class="docutils literal">root</span>, e.g.:</p> 997 <pre class="literal-block">sudo pip install docutils</pre> 998 </li> 999 </ul> 1000 </section> 1001 <section id="windows"> 1002 <h3><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">Windows</a></h3> 1003 <ul> 1004 <li><p>The Python FAQ explains <a class="reference external" href="https://docs.python.org/3/faq/windows.html#how-do-i-run-a-python-program-under-windows">how to run a Python program under Windows</a>.</p> 1005 </li> 1006 <li><p>Usually, <a class="reference external" href="https://pypi.org/project/pip/">pip</a> is automatically installed if you are using Python 1007 downloaded from <a class="reference external" href="https://python.org">https://python.org</a>. If not, see the 1008 <a class="reference external" href="https://pip.pypa.io/en/stable/installation/">pip documentation</a>.</p></li> 1009 <li><p>The command window should recognise the word <span class="docutils literal">py</span> as an instruction to 1010 start the interpreter, e.g.</p> 1011 <blockquote> 1012 <p>py -m pip install docutils</p> 1013 </blockquote> 1014 <p>If this does not work, you may have to specify the full path to the 1015 Python executable.</p> 1016 </li> 1017 </ul> 1018 </section> 1019 </section> 1020 <section id="usage"> 1021 <h2><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">Usage</a></h2> 1022 <p>Start the "docutils" command line application with:</p> 1023 <pre class="literal-block">docutils [options] [<source> [<destination>]]</pre> 1024 <p>The default action is to convert a <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> document to HTML5, 1025 for example:</p> 1026 <pre class="literal-block">docutils test.rst test.html</pre> 1027 <p>Read the <span class="docutils literal"><span class="pre">--help</span></span> option output for details on options and arguments and 1028 <a class="reference external" href="docs/user/tools.html">Docutils Front-End Tools</a> for the full documentation of the various tools.</p> 1029 <p>For programmatic use of the <cite>docutils</cite> Python package, read the 1030 <a class="reference external" href="/docs/index.html#api-reference-material-for-client-developers">API Reference Material</a> and the source code. 1031 Remaining questions may be answered in the <a class="reference external" href="/docs/index.html">Docutils Project 1032 Documentation</a> or the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing list.</p> 1033 <p>Contributions are welcome!</p> 1034 </section> 1035 <section id="project-files-directories"> 1036 <h2><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">Project Files & Directories</a></h2> 1037 <ul class="simple"> 1038 <li><p>README.rst: You're reading it.</p></li> 1039 <li><p>COPYING.rst: Public Domain Dedication and copyright details for 1040 non-public-domain files (most are PD).</p></li> 1041 <li><p>FAQ.rst: Frequently Asked Questions (with answers!).</p></li> 1042 <li><p>RELEASE-NOTES.rst: Summary of the major changes in recent releases.</p></li> 1043 <li><p>HISTORY.rst: A detailed change log, for the current and all previous 1044 project releases.</p></li> 1045 <li><p>BUGS.rst: Known bugs, and how to report a bug.</p></li> 1046 <li><p>THANKS.rst: List of contributors.</p></li> 1047 <li><p>pyproject.toml: Project metadata. 1048 See "Installation" above.</p></li> 1049 <li><p>docutils: The project source directory, installed as a Python 1050 package.</p></li> 1051 <li><p>docs: The project documentation directory. Read <span class="docutils literal">docs/index.rst</span> 1052 for an overview.</p></li> 1053 <li><p>docs/user: The project user documentation directory. Contains the 1054 following documents, among others:</p> 1055 <ul> 1056 <li><p>docs/user/tools.rst: Docutils Front-End Tools</p></li> 1057 <li><p>docs/user/latex.rst: Docutils LaTeX Writer</p></li> 1058 <li><p>docs/user/rst/quickstart.rst: A ReStructuredText Primer</p></li> 1059 <li><p>docs/user/rst/quickref.html: Quick reStructuredText (HTML only)</p></li> 1060 </ul> 1061 </li> 1062 <li><p>docs/ref: The project reference directory. 1063 <span class="docutils literal">docs/ref/rst/restructuredtext.rst</span> is the reStructuredText 1064 reference.</p></li> 1065 <li><p>licenses: Directory containing copies of license files for 1066 non-public-domain files.</p></li> 1067 <li><p>tools: Directory for Docutils front-end tools. See 1068 <span class="docutils literal">docs/user/tools.rst</span> for documentation.</p></li> 1069 <li><p>test: Unit tests. Not required to use the software, but very useful 1070 if you're planning to modify it. See <a class="reference internal" href="#running-the-test-suite">Running the Test Suite</a> 1071 below.</p></li> 1072 </ul> 1073 </section> 1074 <section id="development-version"> 1075 <h2><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">Development version</a></h2> 1076 <p>While we are trying to follow a "release early & often" policy, 1077 features are added frequently. 1078 We recommend using a current snapshot or a working copy of the repository.</p> 1079 <dl> 1080 <dt>Repository check-out:</dt> 1081 <dd><p>To keep up to date on the latest developments, 1082 use a <a class="reference external" href="docs/dev/repository.html#checking-out-the-repository">working copy</a> of the <a class="reference external" href="docs/dev/repository.html">Docutils version repository</a>.</p> 1083 </dd> 1084 <dt>Snapshots:</dt> 1085 <dd><p>To get a repository <span class="target" id="snapshot">snapshot</span>, go to 1086 <a class="reference external" href="https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/">https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/</a> 1087 and click the download snapshot button.</p> 1088 <p>Unpack in a temporary directory, 1089 <strong>not</strong> directly in Python's <span class="docutils literal"><span class="pre">site-packages</span></span>.</p> 1090 </dd> 1091 </dl> 1092 <p>See the <a class="reference internal" href="#installation">Installation</a> instructions above.</p> 1093 </section> 1094 <section id="converting-the-documentation"> 1095 <h2><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">Converting the documentation</a></h2> 1096 <p>After unpacking and installing the Docutils package, the following 1097 shell commands will generate HTML for all included documentation:</p> 1098 <pre class="literal-block">cd <archive_directory_path> 1099 tools/buildhtml.py .</pre> 1100 <p>On Windows systems, type:</p> 1101 <pre class="literal-block">cd <archive_directory_path> 1102 py tools\buildhtml.py ..</pre> 1103 <p>The final directory name of the <span class="docutils literal"><archive_directory_path></span> is 1104 "docutils" for snapshots. For official releases, the directory may be 1105 called "docutils-X.Y.Z", where "X.Y.Z" is the release version.</p> 1106 <p>Some files may generate system messages (warnings and errors). The 1107 <span class="docutils literal">docs/user/rst/demo.rst</span> file (under the archive directory) contains 1108 five intentional errors. (They test the error reporting mechanism!)</p> 1109 </section> 1110 <section id="running-the-test-suite"> 1111 <h2><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">Running the Test Suite</a></h2> 1112 <p>The test suite is documented in <a class="reference external" href="https://docutils.sourceforge.io/docs/dev/testing.html">Docutils Testing</a> (docs/dev/testing.rst).</p> 1113 <p>To run the entire test suite, open a shell and use the following 1114 commands:</p> 1115 <pre class="literal-block">cd <archive_directory_path>/test 1116 ./alltests.py</pre> 1117 <p>Under Windows, type:</p> 1118 <pre class="literal-block">cd <archive_directory_path>\test 1119 python alltests.py</pre> 1120 <p>You should see a long line of periods, one for each test, and then a 1121 summary like this:</p> 1122 <pre class="literal-block">Ran 1744 tests in 5.859s 1123 1124 OK (skipped=1) 1125 Elapsed time: 6.235 seconds</pre> 1126 <p>The number of tests will grow over time, and the times reported will 1127 depend on the computer running the tests. 1128 Some test are skipped, if optional dependencies (<a class="reference internal" href="#recommendations">recommendations</a>) 1129 are missing. 1130 The difference between the two times represents the time required to set 1131 up the tests (import modules, create data structures, etc.).</p> 1132 <p>A copy of the test output is written to the file <span class="docutils literal">alltests.out</span>.</p> 1133 <p>If any of the tests fail, please <a class="reference external" href="https://sourceforge.net/p/docutils/bugs/">open a bug report</a> or <a class="reference external" href="mailto:docutils-users@lists.sourceforge.net?subject=Test%20suite%20failure">send an email</a> 1134 (see <a class="reference external" href="BUGS.html">Bugs</a>). 1135 Please include all relevant output, information about your operating 1136 system, Python version, and Docutils version. To see the Docutils 1137 version, look at the test output or use</p> 1138 <pre class="literal-block">docutils --version</pre> 1139 </section> 1140 <section id="getting-help"> 1141 <h2><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">Getting Help</a></h2> 1142 <p>All documentation can be reached from the <a class="reference external" href="docs/index.html">Project Documentation 1143 Overview</a>.</p> 1144 <p>The SourceForge <a class="reference external" href="https://sourceforge.net/p/docutils">project page</a> has links to the tracker, mailing 1145 lists, and code repository.</p> 1146 <p>If you have further questions or need assistance with Docutils or 1147 reStructuredText, please post a message to the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing 1148 list.</p> 1149 <!-- Emacs settings 1150 1151 Local Variables: 1152 mode: indented-text 1153 mode: rst 1154 indent-tabs-mode: nil 1155 sentence-end-double-space: t 1156 fill-column: 70 1157 End: --> 1158 </section> 1159 </main> 1160 </body> 1161 </html>