CINXE.COM

<!doctype html> <html class="no-js" lang="en" data-content_root="../../"> <head><meta charset="utf-8"/> <meta name="viewport" content="width=device-width,initial-scale=1"/> <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="Getting started" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://devguide.python.org/documentation/start-documenting/" /> <meta property="og:site_name" content="Python Developer's Guide" /> <meta property="og:description" content="The Python language has a substantial body of documentation, much of it contributed by various authors. The markup used for the Python documentation is reStructuredText, developed by the docutils p..." /> <meta property="og:image" content="https://devguide.python.org/_static/og-image-200x200.png" /> <meta property="og:image:alt" content="Python Developer's Guide" /> <meta name="description" content="The Python language has a substantial body of documentation, much of it contributed by various authors. The markup used for the Python documentation is reStructuredText, developed by the docutils p..." /> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="theme-color" content="#3776ab"> <link rel="index" title="Index" href="../../genindex/" /><link rel="search" title="Search" href="../../search/" /><link rel="next" title="Helping with documentation" href="../help-documenting/" /><link rel="prev" title="Documentation" href="../" /> <link rel="shortcut icon" href="../../_static/favicon.png"/> <title>Getting started</title> <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=8f2a1f02" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=354aac6f" /> <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../../_static/tabs.css?v=4c969af8" /> <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?v=302659d7" /> <link rel="stylesheet" type="text/css" href="../../_static/devguide_overrides.css?v=3fc75fb5" /> <style> body { --color-code-background: #f8f8f8; --color-code-foreground: black; } @media not print { body[data-theme="dark"] { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } @media (prefers-color-scheme: dark) { body:not([data-theme="light"]) { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } } } </style><script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="cpython-devguide" /><meta name="readthedocs-version-slug" content="latest" /><meta name="readthedocs-resolver-filename" content="/documentation/start-documenting/" /><meta name="readthedocs-http-status" content="200" /></head> <body> <script> document.body.dataset.theme = localStorage.getItem("theme") || "auto"; </script> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-toc" viewBox="0 0 24 24"> <title>Contents</title> <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line> <line x1="3" y1="6" x2="21" y2="6"></line> <line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24"> <title>Light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24"> <title>Dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> </svg> </symbol> <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> <title>Auto light/dark, in light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> <circle cx="14.5" cy="9.55" r="3.6"/> </svg> </symbol> <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> <title>Auto light/dark, in dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-custom-derived-from-feather-sun-and-tabler-moon"> <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> </svg> </symbol> <symbol id="svg-pencil" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> <path d="M13.5 6.5l4 4" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> <symbol id="svg-eye" viewBox="0 0 24 24"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> <path d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> <path d="M20 21l2 -2l-2 -2" /> <path d="M17 17l-2 2l2 2" /> </svg> </symbol> </svg> <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> <label class="overlay sidebar-overlay" for="__navigation"> <div class="visually-hidden">Hide navigation sidebar</div> </label> <label class="overlay toc-overlay" for="__toc"> <div class="visually-hidden">Hide table of contents sidebar</div> </label> <a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> <div class="page"> <header class="mobile-header"> <div class="header-left"> <label class="nav-overlay-icon" for="__navigation"> <div class="visually-hidden">Toggle site navigation sidebar</div> <i class="icon"><svg><use href="#svg-menu"></use></svg></i> </label> </div> <div class="header-center"> <a href="../../"><div class="brand">Python Developer's Guide</div></a> </div> <div class="header-right"> <div class="theme-toggle-container theme-toggle-header"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-header-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> </header> <aside class="sidebar-drawer"> <div class="sidebar-container"> <div class="sidebar-sticky"><a class="sidebar-brand" href="../../"> <div class="sidebar-logo-container"> <img class="sidebar-logo" src="../../_static/python-logo.svg" alt="Logo"/> </div> <span class="sidebar-brand-text">Python Developer's Guide</span> </a><form class="sidebar-search-container" method="get" action="../../search/" role="search"> <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </form> <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> <ul class="current"> <li class="toctree-l1 has-children"><a class="reference internal" href="../../getting-started/">Getting started</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Getting started</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../getting-started/setup-building/">Setup and building</a></li> <li class="toctree-l2"><a class="reference internal" href="../../getting-started/fixing-issues/">Fixing “easy” issues (and beyond)</a></li> <li class="toctree-l2"><a class="reference internal" href="../../getting-started/git-boot-camp/">Git bootcamp and cheat sheet</a></li> <li class="toctree-l2"><a class="reference internal" href="../../getting-started/pull-request-lifecycle/">Lifecycle of a pull request</a></li> <li class="toctree-l2"><a class="reference internal" href="../../getting-started/getting-help/">Where to get help</a></li> <li class="toctree-l2"><a class="reference internal" href="../../getting-started/generative-ai/">Generative AI</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../developer-workflow/">Development workflow</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Development workflow</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/communication-channels/">Following Python’s development</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/development-cycle/">Development cycle</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/stdlib/">Adding to the stdlib</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/extension-modules/">Standard library extension modules</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/c-api/">Changing Python’s C API</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/lang-changes/">Changing the Python language</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/grammar/">Changing CPython’s grammar</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/porting/">Porting to a new platform</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/sbom/">Software Bill-of-Materials (SBOM)</a></li> <li class="toctree-l2"><a class="reference internal" href="../../developer-workflow/psrt/">Python Security Response Team (PSRT)</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../triage/">Issues and triaging</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Issues and triaging</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../triage/issue-tracker/">Issue tracker</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/triaging/">Triaging an issue</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/labels/">GitHub labels</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/github-bpo-faq/">GitHub issues for BPO users</a></li> <li class="toctree-l2"><a class="reference internal" href="../../triage/triage-team/">Triage Team</a></li> </ul> </li> <li class="toctree-l1 current has-children"><a class="reference internal" href="../">Documentation</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of Documentation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current"> <li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Getting started</a></li> <li class="toctree-l2"><a class="reference internal" href="../help-documenting/">Helping with documentation</a></li> <li class="toctree-l2"><a class="reference internal" href="../style-guide/">Style guide</a></li> <li class="toctree-l2"><a class="reference internal" href="../markup/">reStructuredText markup</a></li> <li class="toctree-l2"><a class="reference internal" href="../translating/">Translating</a></li> <li class="toctree-l2"><a class="reference internal" href="../devguide/">Helping with the Developer’s Guide</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../testing/">Testing and buildbots</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of Testing and buildbots</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../testing/run-write-tests/">Running and writing tests</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/silence-warnings/">Silence warnings from the test suite</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/coverage/">Increase test coverage</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/buildbots/">Working with buildbots</a></li> <li class="toctree-l2"><a class="reference internal" href="../../testing/new-buildbot-worker/">New buildbot workers</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../development-tools/">Development tools</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of Development tools</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/clinic/">Argument Clinic</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/gdb/">GDB support</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/clang/">Dynamic analysis with Clang</a></li> <li class="toctree-l2"><a class="reference internal" href="../../development-tools/warnings/">Tools for tracking compiler warnings</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../core-developers/">Core developers</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of Core developers</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/responsibilities/">Responsibilities</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/committing/">Accepting pull requests</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/experts/">Experts index</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/developer-log/">Developer log</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/motivations/">Motivations and affiliations</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/become-core-developer/">How to become a core developer</a></li> <li class="toctree-l2"><a class="reference internal" href="../../core-developers/memorialization/">Memorialization</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../internals/">CPython’s internals</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of CPython’s internals</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../internals/exploring/">CPython source code</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/parser/">Guide to the parser</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/compiler/">Compiler design</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/interpreter/">The bytecode interpreter</a></li> <li class="toctree-l2"><a class="reference internal" href="../../internals/garbage-collector/">Garbage collector design</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../versions/">Status of Python versions</a></li> <li class="toctree-l1 has-children"><a class="reference internal" href="../../contrib/">Python Contributor’s Guide (draft)</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle navigation of Python Contributor’s Guide (draft)</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../../contrib/contrib-plan/">[Plan for the Contributor’s Guide]</a></li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/intro/">Introduction</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/project/">The CPython project</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle navigation of The CPython project</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/conduct/">Code of Conduct</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/roles/">Roles</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/governance/">Governance</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/generative-ai/">Generative AI</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/github/">GitHub</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/channels/">Communication channels</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/project/outreach/">Outreach</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/get-started/">Getting started</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/triage/">Issues and triaging</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle navigation of Issues and triaging</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/issue-tracker/">Issue tracker</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/triaging/">Triaging an issue</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/labels/">GitHub labels</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/reviewing/">Reviewing</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/triage/triage-team/">Triage Team</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/code/">Code contributions</a><input class="toctree-checkbox" id="toctree-checkbox-12" name="toctree-checkbox-12" role="switch" type="checkbox"/><label for="toctree-checkbox-12"><div class="visually-hidden">Toggle navigation of Code contributions</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/code/setup/">Setup and building</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/code/git/">Git tips</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/code/pull-request-lifecycle/">Pull request lifecycle</a></li> <li class="toctree-l3 has-children"><a class="reference internal" href="../../contrib/code/developer-workflow/">Development workflow</a><input class="toctree-checkbox" id="toctree-checkbox-13" name="toctree-checkbox-13" role="switch" type="checkbox"/><label for="toctree-checkbox-13"><div class="visually-hidden">Toggle navigation of Development workflow</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/communication-channels/">Following Python’s development</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/development-cycle/">Development cycle</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/stdlib/">Adding to the stdlib</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/extension-modules/">Standard library extension modules</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/c-api/">Changing Python’s C API</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/lang-changes/">Changing the Python language</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/grammar/">Changing CPython’s grammar</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/porting/">Porting to a new platform</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/sbom/">Software Bill-of-Materials (SBOM)</a></li> <li class="toctree-l4"><a class="reference internal" href="../../developer-workflow/psrt/">Python Security Response Team (PSRT)</a></li> </ul> </li> <li class="toctree-l3 has-children"><a class="reference internal" href="../../contrib/code/testing/">Testing and buildbots</a><input class="toctree-checkbox" id="toctree-checkbox-14" name="toctree-checkbox-14" role="switch" type="checkbox"/><label for="toctree-checkbox-14"><div class="visually-hidden">Toggle navigation of Testing and buildbots</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../../testing/run-write-tests/">Running and writing tests</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/silence-warnings/">Silence warnings from the test suite</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/coverage/">Increase test coverage</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/buildbots/">Working with buildbots</a></li> <li class="toctree-l4"><a class="reference internal" href="../../testing/new-buildbot-worker/">New buildbot workers</a></li> </ul> </li> <li class="toctree-l3 has-children"><a class="reference internal" href="../../contrib/code/development-tools/">Development tools</a><input class="toctree-checkbox" id="toctree-checkbox-15" name="toctree-checkbox-15" role="switch" type="checkbox"/><label for="toctree-checkbox-15"><div class="visually-hidden">Toggle navigation of Development tools</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/clinic/">Argument Clinic</a></li> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/gdb/">GDB support</a></li> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/clang/">Dynamic analysis with Clang</a></li> <li class="toctree-l4"><a class="reference internal" href="../../development-tools/warnings/">Tools for tracking compiler warnings</a></li> </ul> </li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/doc/">Documentation contributions</a><input class="toctree-checkbox" id="toctree-checkbox-16" name="toctree-checkbox-16" role="switch" type="checkbox"/><label for="toctree-checkbox-16"><div class="visually-hidden">Toggle navigation of Documentation contributions</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/start-documenting/">Getting started</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/help-documenting/">Helping with documentation</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/style-guide/">Style guide</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/markup/">reStructuredText markup</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/pull-request-lifecycle/">Pull request lifecycle</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/translating/">Translating</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/doc/devguide/">Helping with the Developer’s Guide</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../../contrib/core-team/">Core team</a><input class="toctree-checkbox" id="toctree-checkbox-17" name="toctree-checkbox-17" role="switch" type="checkbox"/><label for="toctree-checkbox-17"><div class="visually-hidden">Toggle navigation of Core team</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/responsibilities/">Responsibilities</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/committing/">Accepting pull requests</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/experts/">Experts index</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/developer-log/">Developer log</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/motivations/">Motivations and affiliations</a></li> <li class="toctree-l3"><a class="reference internal" href="../../contrib/core-team/join-team/">How to join the core team</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/user-success/">Accessibility, design, and user success</a></li> <li class="toctree-l2"><a class="reference internal" href="../../contrib/security/">Security and infrastructure contributions</a></li> </ul> </li> </ul> </div> </div> </div> </div> </aside> <div class="main"> <div class="content"> <div class="article-container"> <a href="#" class="back-to-top muted-link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> </svg> <span>Back to top</span> </a> <div class="content-icon-container"> <div class="view-this-page"> <a class="muted-link" href="https://github.com/python/devguide/blob/main/documentation/start-documenting.rst?plain=true" title="View this page"> <svg><use href="#svg-eye"></use></svg> <span class="visually-hidden">View this page</span> </a> </div><div class="edit-this-page"> <a class="muted-link" href="https://github.com/python/devguide/edit/main/documentation/start-documenting.rst" title="Edit this page"> <svg><use href="#svg-pencil"></use></svg> <span class="visually-hidden">Edit this page</span> </a> </div><div class="theme-toggle-container theme-toggle-content"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-content-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> <article role="main" id="furo-main-content"> <section id="getting-started"> <span id="documenting"></span><span id="start-documenting"></span><h1>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading">¶</a></h1> <script> document.addEventListener('DOMContentLoaded', function() { activateTab(getOS()); }); </script><p>The Python language has a substantial body of documentation, much of it contributed by various authors. The markup used for the Python documentation is <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>, developed by the <a class="reference external" href="https://docutils.sourceforge.io/">docutils</a> project, amended by custom directives and using a toolset named <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a> to post-process the HTML output.</p> <p>The documentation in HTML, PDF or EPUB format is generated from text files written using the <a class="reference internal" href="../markup/#markup"><span class="std std-ref">reStructuredText format</span></a> and contained in the <a class="reference internal" href="../../getting-started/setup-building/#setup"><span class="std std-ref">CPython Git repository</span></a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If you’re interested in contributing to Python’s documentation, there’s no need to write reStructuredText if you’re not so inclined; plain text contributions are more than welcome as well. Send an e-mail to <a class="reference external" href="mailto:docs%40python.org">docs<span>@</span>python<span>.</span>org</a> or open an issue on the <a class="reference external" href="https://docs.python.org/3/bugs.html#reporting-bugs" title="(in Python v3.13)"><span class="xref std std-ref">tracker</span></a>.</p> </div> <section id="introduction"> <h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2> <p>Python’s documentation has long been considered to be good for a free programming language. There are a number of reasons for this, the most important being the early commitment of Python’s creator, Guido van Rossum, to providing documentation on the language and its libraries, and the continuing involvement of the user community in providing assistance for creating and maintaining documentation.</p> <p>The involvement of the community takes many forms, from authoring to bug reports to just plain complaining when the documentation could be more complete or easier to use.</p> <p>This section is aimed at authors and potential authors of documentation for Python. More specifically, it is for people contributing to the standard documentation and developing additional documents using the same tools as the standard documents. This guide will be less useful for authors using the Python documentation tools for topics other than Python, and less useful still for authors not using the tools at all.</p> <p>If your interest is in contributing to the Python documentation, but you don’t have the time or inclination to learn reStructuredText and the markup structures documented here, there’s a welcoming place for you among the Python contributors as well. Any time you feel that you can clarify existing documentation or provide documentation that’s missing, the existing documentation team will gladly work with you to integrate your text, dealing with the markup for you. Please don’t let the material in this section stand between the documentation and your desire to help out!</p> </section> <section id="building-the-documentation"> <span id="building-doc"></span><h2>Building the documentation<a class="headerlink" href="#building-the-documentation" title="Link to this heading">¶</a></h2> <p>To build the documentation, follow the steps in one of the sections below. You can view the documentation after building the HTML by opening the file <code class="file docutils literal notranslate"><span class="pre">Doc/build/html/index.html</span></code> in a web browser.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The following instructions all assume your current working dir is the <code class="docutils literal notranslate"><span class="pre">Doc</span></code> subdirectory in your <a class="reference internal" href="../../getting-started/setup-building/#checkout"><span class="std std-ref">CPython repository clone</span></a>. Make sure to switch to it with <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">Doc</span></code> if necessary.</p> </div> <section id="create-a-virtual-environment"> <span id="doc-create-venv"></span><h3>Create a virtual environment<a class="headerlink" href="#create-a-virtual-environment" title="Link to this heading">¶</a></h3> <p id="doc-create-venv-windows"><span id="doc-create-venv-unix"></span>You can create a new <a class="reference external" href="https://docs.python.org/3/library/venv.html#module-venv" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">venv</span></code></a> with the required dependencies using:</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--0-input--1" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--1">Unix/macOS</label><div class="tab-content docutils container"> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>venv </pre></div> </div> <p>Building the docs with <strong class="program">make</strong> will automatically use this environment without you having to activate it.</p> </div> <input class="tab-input" id="tab-set--0-input--2" name="tab-set--0" type="radio"><label class="tab-label" for="tab-set--0-input--2">Windows</label><div class="tab-content docutils container"> <p><a class="reference external" href="https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment">Create a new virtual environment</a> manually. Always be sure to <a class="reference external" href="https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment">activate this environment</a> before building the documentation.</p> </div> </div> </section> <section id="build-using-make-make-bat"> <span id="doc-build-make"></span><span id="using-make-make-bat"></span><span id="building-using-make"></span><h3>Build using make / make.bat<a class="headerlink" href="#build-using-make-make-bat" title="Link to this heading">¶</a></h3> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--1-input--1" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--1">Unix/macOS</label><div class="tab-content docutils container"> <p>A Unix <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> is provided, <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/Doc/Makefile">Doc/Makefile</a>.</p> </div> <input class="tab-input" id="tab-set--1-input--2" name="tab-set--1" type="radio"><label class="tab-label" for="tab-set--1-input--2">Windows</label><div class="tab-content docutils container"> <p>A Windows <code class="docutils literal notranslate"><span class="pre">make.bat</span></code> is provided, <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/Doc/make.bat">Doc/make.bat</a>, which attempts to emulate the Unix <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> as closely as practical.</p> <div class="admonition important"> <p class="admonition-title">Important</p> <p>The Windows <code class="docutils literal notranslate"><span class="pre">make.bat</span></code> batch file lacks a <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">venv</span></code> target. Instead, it automatically installs any missing dependencies into the currently activated environment (or the base Python, if none). Make sure the environment you <a class="reference internal" href="#doc-create-venv-windows"><span class="std std-ref">created above</span></a> is <a class="reference external" href="https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment">activated</a> before running <code class="docutils literal notranslate"><span class="pre">make.bat</span></code>.</p> </div> </div> </div> <p>To build the docs as HTML, run:</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--2-input--1" name="tab-set--2" type="radio"><label class="tab-label" for="tab-set--2-input--1">Unix/macOS</label><div class="tab-content docutils container"> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>html </pre></div> </div> </div> <input class="tab-input" id="tab-set--2-input--2" name="tab-set--2" type="radio"><label class="tab-label" for="tab-set--2-input--2">Windows</label><div class="tab-content docutils container"> <div class="highlight-dosbatch notranslate"><div class="highlight"><pre><span></span>.\make html </pre></div> </div> </div> </div> <div class="admonition tip"> <p class="admonition-title">Tip</p> <ul class="simple"> <li><p>Replace <code class="docutils literal notranslate"><span class="pre">html</span></code> with <code class="docutils literal notranslate"><span class="pre">htmlview</span></code> to open the docs in a web browser once the build completes.</p></li> <li><p>Replace <code class="docutils literal notranslate"><span class="pre">html</span></code> with <code class="docutils literal notranslate"><span class="pre">htmllive</span></code> to rebuild the docs, start a local server, and automatically reload the page in your browser when you make changes to reST files (Unix only).</p></li> </ul> </div> <p>To check the docs for common errors with <a class="reference external" href="https://github.com/sphinx-contrib/sphinx-lint">Sphinx Lint</a> (which is run on all <a class="reference internal" href="../../getting-started/pull-request-lifecycle/#pullrequest"><span class="std std-ref">pull requests</span></a>), use:</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--3-input--1" name="tab-set--3" type="radio"><label class="tab-label" for="tab-set--3-input--1">Unix/macOS</label><div class="tab-content docutils container"> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>check </pre></div> </div> </div> <input class="tab-input" id="tab-set--3-input--2" name="tab-set--3" type="radio"><label class="tab-label" for="tab-set--3-input--2">Windows</label><div class="tab-content docutils container"> <div class="highlight-dosbatch notranslate"><div class="highlight"><pre><span></span>.\make check </pre></div> </div> </div> </div> <p>To list other supported <strong class="program">make</strong> targets, run:</p> <div class="tab-set docutils container"> <input checked="True" class="tab-input" id="tab-set--4-input--1" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--1">Unix/macOS</label><div class="tab-content docutils container"> <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span><span class="nb">help</span> </pre></div> </div> </div> <input class="tab-input" id="tab-set--4-input--2" name="tab-set--4" type="radio"><label class="tab-label" for="tab-set--4-input--2">Windows</label><div class="tab-content docutils container"> <div class="highlight-dosbatch notranslate"><div class="highlight"><pre><span></span>.\make help </pre></div> </div> </div> </div> <p>See <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/Doc/README.rst">Doc/README.rst</a> for more information.</p> </section> <section id="build-using-sphinx-directly"> <span id="doc-build-sphinx"></span><span id="using-sphinx-build"></span><h3>Build using Sphinx directly<a class="headerlink" href="#build-using-sphinx-directly" title="Link to this heading">¶</a></h3> <p>Advanced users may want to invoke Sphinx directly, to pass specialized options or to handle specific use cases.</p> <p>Make sure the environment you <a class="reference internal" href="#doc-create-venv-windows"><span class="std std-ref">created above</span></a> is <a class="reference external" href="https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment">activated</a>. Then, install the documentation requirements, <a class="extlink-cpy-file reference external" href="https://github.com/python/cpython/blob/main/Doc/requirements.txt">Doc/requirements.txt</a>. Using pip:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--upgrade<span class="w"> </span>-r<span class="w"> </span>requirements.txt </pre></div> </div> <p>Finally, directly invoke Sphinx with:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>-m<span class="w"> </span>sphinx<span class="w"> </span>-b<span class="w"> </span>html<span class="w"> </span>.<span class="w"> </span>build/html </pre></div> </div> <p>To use a different <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/builders/index.html">Sphinx builder</a>, replace <code class="docutils literal notranslate"><span class="pre">html</span></code> above with the desired builder <code class="docutils literal notranslate"><span class="pre">name</span></code>.</p> </section> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="../help-documenting/"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Helping with documentation</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="../"> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> <div class="page-info"> <div class="context"> <span>Previous</span> </div> <div class="title">Documentation</div> </div> </a> </div> <div class="bottom-of-page"> <div class="left-details"> <div class="copyright"> Copyright © 2011 Python Software Foundation </div> Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s <a href="https://github.com/pradyunsg/furo">Furo</a> </div> <div class="right-details"> </div> </div> </footer> </div> <aside class="toc-drawer"> <div class="toc-sticky toc-scroll"> <div class="toc-title-container"> <span class="toc-title"> On this page </span> </div> <div class="toc-tree-container"> <div class="toc-tree"> <ul> <li><a class="reference internal" href="#">Getting started</a><ul> <li><a class="reference internal" href="#introduction">Introduction</a></li> <li><a class="reference internal" href="#building-the-documentation">Building the documentation</a><ul> <li><a class="reference internal" href="#create-a-virtual-environment">Create a virtual environment</a></li> <li><a class="reference internal" href="#build-using-make-make-bat">Build using make / make.bat</a></li> <li><a class="reference internal" href="#build-using-sphinx-directly">Build using Sphinx directly</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </aside> </div> </div><script src="../../_static/documentation_options.js?v=187304be"></script> <script src="../../_static/doctools.js?v=9bcbadda"></script> <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../../_static/scripts/furo.js?v=5fa4622c"></script> <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../../_static/copybutton.js?v=c136e461"></script> <script src="../../_static/tabs.js?v=3ee01567"></script> <script src="../../_static/activate_tab.js?v=3ac9c400"></script> </body> </html>