nep-0044-restructuring-numpy-docs.html


<!DOCTYPE html>


<html lang="en" data-content_root="./" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>NEP 44 — Restructuring the NumPy documentation &#8212; NumPy Enhancement Proposals</title>
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
  </script>
  <!--
    this give us a css class that will be invisible only if js is disabled
  -->
  <noscript>
    <style>
      .pst-js-only { display: none !important; }

    </style>
  </noscript>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />

    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
  
  <!-- So that users can add custom icons -->
  <script src="_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script>
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />

    <script src="_static/documentation_options.js?v=7f41d439"></script>
    <script src="_static/doctools.js?v=888ff710"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'nep-0044-restructuring-numpy-docs';</script>
    <link rel="icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="NEP 51 — Changing the representation of NumPy scalars" href="nep-0051-scalar-representation.html" />
    <link rel="prev" title="NEP 42 — New and extensible DTypes" href="nep-0042-new-dtypes.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
  <meta name="docsearch:version" content="" />
    <meta name="docbuild:last-update" content="Jun 20, 2025"/>
  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
  
  <div id="pst-scroll-pixel-helper"></div>
  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>Back to top</button>

  
  <dialog id="pst-search-dialog">
    
<form class="bd-search d-flex align-items-center"
      action="search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         placeholder="Search the docs ..."
         aria-label="Search the docs ..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
  </dialog>

  <div class="pst-async-banner-revealer d-none">
  <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>

  
    <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
  <button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
    <span class="fa-solid fa-bars"></span>
  </button>
  
  
  <div class="col-lg-3 navbar-header-items__start">
    
      <div class="navbar-item">

  
<a class="navbar-brand logo" href="content.html">
  
  
    <img src="_static/numpylogo.svg" class="logo__image only-light" alt="NumPy Enhancement Proposals - Home"/>
    <img src="_static/numpylogo_dark.svg" class="logo__image only-dark pst-js-only" alt="NumPy Enhancement Proposals - Home"/>
  
  
</a></div>
    
  </div>
  
  <div class="col-lg-9 navbar-header-items">
    
    <div class="me-auto navbar-header-items__center">
      
        <div class="navbar-item">
<nav>
  <ul class="bd-navbar-elements navbar-nav">
    
<li class="nav-item current active">
  <a class="nav-link nav-internal" href="index.html">
    Index
  </a>
</li>


<li class="nav-item ">
  <a class="nav-link nav-internal" href="scope.html">
    The Scope of NumPy
  </a>
</li>


<li class="nav-item ">
  <a class="nav-link nav-internal" href="roadmap.html">
    Current roadmap
  </a>
</li>


<li class="nav-item ">
  <a class="nav-link nav-external" href="https://github.com/numpy/numpy/issues?q=is%3Aopen+is%3Aissue+label%3A%2223+-+Wish+List%22">
    Wishlist
  </a>
</li>

  </ul>
</nav></div>
      
    </div>
    
    
    <div class="navbar-header-items__end">
      
        <div class="navbar-item navbar-persistent--container">
          

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
        </div>
      
      
        <div class="navbar-item">

<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button></div>
      
        <div class="navbar-item"><ul class="navbar-icon-links"
    aria-label="Icon Links">
        <li class="nav-item">
          
          
          <a href="https://github.com/numpy/numpy" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i>
            <span class="sr-only">GitHub</span></a>
        </li>
</ul></div>
      
    </div>
    
  </div>
  
  
    <div class="navbar-persistent--mobile">

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
    </div>
  

    <button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
      <span class="fa-solid fa-outdent"></span>
    </button>
  
</div>

    </header>
  

  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      
      <dialog id="pst-primary-sidebar-modal"></dialog>
      <div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
        

  <div class="sidebar-header-items sidebar-primary__section">
    
    
      <div class="sidebar-header-items__center">
        
          
            <div class="navbar-item">
<nav>
  <ul class="bd-navbar-elements navbar-nav">
    
<li class="nav-item current active">
  <a class="nav-link nav-internal" href="index.html">
    Index
  </a>
</li>


<li class="nav-item ">
  <a class="nav-link nav-internal" href="scope.html">
    The Scope of NumPy
  </a>
</li>


<li class="nav-item ">
  <a class="nav-link nav-internal" href="roadmap.html">
    Current roadmap
  </a>
</li>


<li class="nav-item ">
  <a class="nav-link nav-external" href="https://github.com/numpy/numpy/issues?q=is%3Aopen+is%3Aissue+label%3A%2223+-+Wish+List%22">
    Wishlist
  </a>
</li>

  </ul>
</nav></div>
          
        
      </div>
    
    
      <div class="sidebar-header-items__end">
        
          <div class="navbar-item">

<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button></div>
        
          <div class="navbar-item"><ul class="navbar-icon-links"
    aria-label="Icon Links">
        <li class="nav-item">
          
          
          <a href="https://github.com/numpy/numpy" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i>
            <span class="sr-only">GitHub</span></a>
        </li>
</ul></div>
        
      </div>
    
  </div>
  
    <div class="sidebar-primary-items__start sidebar-primary__section">
        <div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
     aria-label="Section Navigation">
  <p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
  <div class="bd-toc-item navbar-nav"><ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="scope.html">The Scope of NumPy</a></li>
<li class="toctree-l1"><a class="reference internal" href="roadmap.html">Current roadmap</a></li>
</ul>
<ul class="current nav bd-sidenav">
<li class="toctree-l1 has-children"><a class="reference internal" href="meta.html">Meta-NEPs (NEPs about NEPs or active Processes)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0000.html">NEP 0 — Purpose and process</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0023-backwards-compatibility.html">NEP 23 — Backwards compatibility and deprecation policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0036-fair-play.html">NEP 36 — Fair play</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0045-c_style_guide.html">NEP 45 — C style guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0046-sponsorship-guidelines.html">NEP 46 — NumPy sponsorship guidelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0048-spending-project-funds.html">NEP 48 — Spending NumPy project funds</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-template.html">NEP X — Template and instructions</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="provisional.html">Provisional NEPs (provisionally accepted; interface may change)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul class="simple">
</ul>
</details></li>
<li class="toctree-l1 current active has-children"><a class="reference internal" href="accepted.html">Accepted NEPs (implementation in progress)</a><details open="open"><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="nep-0041-improved-dtype-support.html">NEP 41 — First step towards a new datatype system</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0042-new-dtypes.html">NEP 42 — New and extensible DTypes</a></li>
<li class="toctree-l2 current active"><a class="current reference internal" href="#">NEP 44 — Restructuring the NumPy documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0051-scalar-representation.html">NEP 51 — Changing the representation of NumPy scalars</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0054-simd-cpp-highway.html">NEP 54 — SIMD infrastructure evolution: adopting Google Highway when moving to C++</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="open.html">Open NEPs (under consideration)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0043-extensible-ufuncs.html">NEP 43 — Enhancing the extensibility of UFuncs</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0053-c-abi-evolution.html">NEP 53 — Evolving the NumPy C-API for NumPy 2.0</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="finished.html">Finished NEPs</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0001-npy-format.html">NEP 1 — A simple file format for NumPy arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0005-generalized-ufuncs.html">NEP 5 — Generalized universal functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0007-datetime-proposal.html">NEP 7 — A proposal for implementing some date/time types in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0010-new-iterator-ufunc.html">NEP 10 — Optimizing iterator/UFunc performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0013-ufunc-overrides.html">NEP 13 — A mechanism for overriding Ufuncs</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0014-dropping-python2.7-proposal.html">NEP 14 — Plan for dropping Python 2.7 support</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0015-merge-multiarray-umath.html">NEP 15 — Merging multiarray and umath</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0018-array-function-protocol.html">NEP 18 — A dispatch mechanism for NumPy's high level array functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0019-rng-policy.html">NEP 19 — Random number generator policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0020-gufunc-signature-enhancement.html">NEP 20 — Expansion of generalized universal function signatures</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0022-ndarray-duck-typing-overview.html">NEP 22 — Duck typing for NumPy arrays – high level overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0027-zero-rank-arrarys.html">NEP 27 — Zero rank arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0028-website-redesign.html">NEP 28 — numpy.org website redesign</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0029-deprecation_policy.html">NEP 29 — Recommend Python and NumPy version support as a community policy standard</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0032-remove-financial-functions.html">NEP 32 — Remove the financial functions from NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0034-infer-dtype-is-object.html">NEP 34 — Disallow inferring ``dtype=object`` from sequences</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0035-array-creation-dispatch-with-array-function.html">NEP 35 — Array creation dispatching with __array_function__</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0038-SIMD-optimizations.html">NEP 38 — Using SIMD optimization instructions for performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0040-legacy-datatype-impl.html">NEP 40 — Legacy datatype implementation in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0049.html">NEP 49 — Data allocation strategies</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0050-scalar-promotion.html">NEP 50 — Promotion rules for Python scalars</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0052-python-api-cleanup.html">NEP 52 — Python API cleanup for NumPy 2.0</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0055-string_dtype.html">NEP 55 — Add a UTF-8 variable-width string DType to NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0056-array-api-main-namespace.html">NEP 56 — Array API standard support in NumPy's main namespace</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="deferred.html">Deferred and Superseded NEPs</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0002-warnfix.html">NEP 2 — A proposal to build numpy without warning with a big set of warning flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0003-math_config_clean.html">NEP 3 — Cleaning the math configuration of numpy.core</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0004-datetime-proposal3.html">NEP 4 — A (third) proposal for implementing some date/time types in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0006-newbugtracker.html">NEP 6 — Replacing Trac with a different bug tracker</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0008-groupby_additions.html">NEP 8 — A proposal for adding groupby functionality to NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0009-structured_array_extensions.html">NEP 9 — Structured array extensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0011-deferred-ufunc-evaluation.html">NEP 11 — Deferred UFunc evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0012-missing-data.html">NEP 12 — Missing data functionality in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0021-advanced-indexing.html">NEP 21 — Simplified and explicit advanced indexing</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0024-missing-data-2.html">NEP 24 — Missing data functionality - alternative 1 to NEP 12</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0025-missing-data-3.html">NEP 25 — NA support via special dtypes</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0026-missing-data-summary.html">NEP 26 — Summary of missing data NEPs and discussion</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0030-duck-array-protocol.html">NEP 30 — Duck typing for NumPy arrays - implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0031-uarray.html">NEP 31 — Context-local and global overrides of the NumPy API</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0037-array-module.html">NEP 37 — A dispatch protocol for NumPy-like modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0047-array-api-standard.html">NEP 47 — Adopting the array API standard</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="rejected.html">Rejected and Withdrawn NEPs</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0016-abstract-array.html">NEP 16 — An abstract base class for identifying "duck arrays"</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0017-split-out-maskedarray.html">NEP 17 — Split out masked arrays</a></li>
</ul>
</details></li>
</ul>
</div>
</nav></div>
    </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
      <div class="sidebar-primary-item">
<div id="ethical-ad-placement"
      class="flat"
      data-ea-publisher="readthedocs"
      data-ea-type="readthedocs-sidebar"
      data-ea-manual="true">
</div></div>
  </div>


      </div>
      
      <main id="main-content" class="bd-main" role="main">
        
        
          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item">

<nav aria-label="Breadcrumb" class="d-print-none">
  <ul class="bd-breadcrumbs">
    
    <li class="breadcrumb-item breadcrumb-home">
      <a href="content.html" class="nav-link" aria-label="Home">
        <i class="fa-solid fa-home"></i>
      </a>
    </li>
    
    <li class="breadcrumb-item"><a href="index.html" class="nav-link">Roadmap &amp; NumPy enhancement proposals</a></li>
    
    
    <li class="breadcrumb-item"><a href="accepted.html" class="nav-link">Accepted NEPs (implementation in progress)</a></li>
    
    <li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">NEP 44 — Restructuring the NumPy documentation</span></li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section id="nep-44-restructuring-the-numpy-documentation">
<span id="nep44"></span><h1>NEP 44 — Restructuring the NumPy documentation<a class="headerlink" href="#nep-44-restructuring-the-numpy-documentation" title="Link to this heading">#</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Ralf Gommers</p>
</dd>
<dt class="field-even">Author<span class="colon">:</span></dt>
<dd class="field-even"><p>Melissa Mendonça</p>
</dd>
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Mars Lee</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>Accepted</p>
</dd>
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>Process</p>
</dd>
<dt class="field-even">Created<span class="colon">:</span></dt>
<dd class="field-even"><p>2020-02-11</p>
</dd>
<dt class="field-odd">Resolution<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://mail.python.org/pipermail/numpy-discussion/2020-March/080467.html">https://mail.python.org/pipermail/numpy-discussion/2020-March/080467.html</a></p>
</dd>
</dl>
<section id="abstract">
<h2>Abstract<a class="headerlink" href="#abstract" title="Link to this heading">#</a></h2>
<p>This document proposes a restructuring of the NumPy Documentation, both in form
and content, with the goal of making it more organized and discoverable for
beginners and experienced users.</p>
</section>
<section id="motivation-and-scope">
<h2>Motivation and scope<a class="headerlink" href="#motivation-and-scope" title="Link to this heading">#</a></h2>
<p>See <a class="reference external" href="https://numpy.org/devdocs/">here</a> for the front page of the latest docs.
The organization is quite confusing and illogical (e.g. user and developer docs
are mixed). We propose the following:</p>
<ul class="simple">
<li><p>Reorganizing the docs into the four categories mentioned in <a class="footnote-reference brackets" href="#id5" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, namely <em>Tutorials</em>, <em>How Tos</em>, <em>Reference Guide</em> and <em>Explanations</em> (more about this below).</p></li>
<li><p>Creating dedicated sections for Tutorials and How-Tos, including orientation
on how to create new content;</p></li>
<li><p>Adding an Explanations section for key concepts and techniques that require
deeper descriptions, some of which will be rearranged from the Reference Guide.</p></li>
</ul>
</section>
<section id="usage-and-impact">
<h2>Usage and impact<a class="headerlink" href="#usage-and-impact" title="Link to this heading">#</a></h2>
<p>The documentation is a fundamental part of any software project, especially
open source projects. In the case of NumPy, many beginners might feel demotivated
by the current structure of the documentation, since it is difficult to discover
what to learn (unless the user has a clear view of what to look for in the
Reference docs, which is not always the case).</p>
<p>Looking at the results of a “NumPy Tutorial” search on any search engine also
gives an idea of the demand for this kind of content. Having official high-level
documentation written using up-to-date content and techniques will certainly
mean more users (and developers/contributors) are involved in the NumPy
community.</p>
</section>
<section id="backward-compatibility">
<h2>Backward compatibility<a class="headerlink" href="#backward-compatibility" title="Link to this heading">#</a></h2>
<p>The restructuring will effectively demand a complete rewrite of links and some
of the current content. Input from the community will be useful for identifying
key links and pages that should not be broken.</p>
</section>
<section id="detailed-description">
<h2>Detailed description<a class="headerlink" href="#detailed-description" title="Link to this heading">#</a></h2>
<p>As discussed in the article <a class="footnote-reference brackets" href="#id5" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, there are four categories of doc content:</p>
<ul class="simple">
<li><p>Tutorials</p></li>
<li><p>How-to guides</p></li>
<li><p>Explanations</p></li>
<li><p>Reference guide</p></li>
</ul>
<p>We propose to use those categories as the ones we use (for writing and
reviewing) whenever we add a new documentation section.</p>
<p>The reasoning for this is that it is clearer both for
developers/documentation writers and to users where each piece of
information should go, and the scope and tone of each document. For
example, if explanations are mixed with basic tutorials, beginners
might be overwhelmed and alienated. On the other hand, if the reference
guide contains basic how-tos, it might be difficult for experienced
users to find the information they need, quickly.</p>
<p>Currently, there are many blogs and tutorials on the internet about NumPy or
using NumPy. One of the issues with this is that if users search for this
information they may end up in an outdated (unofficial) tutorial before
they find the current official documentation. This can be especially
confusing, especially for beginners. Having a better infrastructure for the
documentation also aims to solve this problem by giving users high-level,
up-to-date official documentation that can be easily updated.</p>
<section id="status-and-ideas-of-each-type-of-doc-content">
<h3>Status and ideas of each type of doc content<a class="headerlink" href="#status-and-ideas-of-each-type-of-doc-content" title="Link to this heading">#</a></h3>
<section id="reference-guide">
<h4>Reference guide<a class="headerlink" href="#reference-guide" title="Link to this heading">#</a></h4>
<p>NumPy has a quite complete reference guide. All functions are documented, most
have examples, and most are cross-linked well with <em>See Also</em> sections. Further
improving the reference guide is incremental work that can be done (and is being
done) by many people. There are, however, many explanations in the reference
guide. These can be moved to a more dedicated Explanations section on the docs.</p>
</section>
<section id="how-to-guides">
<h4>How-to guides<a class="headerlink" href="#how-to-guides" title="Link to this heading">#</a></h4>
<p>NumPy does not have many how-to’s. The subclassing and array ducktyping section
may be an example of a how-to. Others that could be added are:</p>
<ul class="simple">
<li><p>Parallelization (controlling BLAS multithreading with <code class="docutils literal notranslate"><span class="pre">threadpoolctl</span></code>, using
multiprocessing, random number generation, etc.)</p></li>
<li><p>Storing and loading data (<code class="docutils literal notranslate"><span class="pre">.npy</span></code>/<code class="docutils literal notranslate"><span class="pre">.npz</span></code> format, text formats, Zarr, HDF5,
Bloscpack, etc.)</p></li>
<li><p>Performance (memory layout, profiling, use with Numba, Cython, or Pythran)</p></li>
<li><p>Writing generic code that works with NumPy, Dask, CuPy, pydata/sparse, etc.</p></li>
</ul>
</section>
<section id="explanations">
<h4>Explanations<a class="headerlink" href="#explanations" title="Link to this heading">#</a></h4>
<p>There is a reasonable amount of content on fundamental NumPy concepts such as
indexing, vectorization, broadcasting, (g)ufuncs, and dtypes. This could be
organized better and clarified to ensure it’s really about explaining the concepts
and not mixed with tutorial or how-to like content.</p>
<p>There are few explanations about anything other than those fundamental NumPy
concepts.</p>
<p>Some examples of concepts that could be expanded:</p>
<ul class="simple">
<li><p>Copies vs. Views;</p></li>
<li><p>BLAS and other linear algebra libraries;</p></li>
<li><p>Fancy indexing.</p></li>
</ul>
<p>In addition, there are many explanations in the Reference Guide, which should be
moved to this new dedicated Explanations section.</p>
</section>
<section id="tutorials">
<h4>Tutorials<a class="headerlink" href="#tutorials" title="Link to this heading">#</a></h4>
<p>There’s a lot of scope for writing better tutorials. We have a new <em>NumPy for
absolute beginners tutorial</em> <a class="footnote-reference brackets" href="#id7" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a> (GSoD project of Anne Bonner). In addition we
need a number of tutorials addressing different levels of experience with Python
and NumPy. This could be done using engaging data sets, ideas or stories. For
example, curve fitting with polynomials and functions in <code class="docutils literal notranslate"><span class="pre">numpy.linalg</span></code> could
be done with the Keeling curve (decades worth of CO2 concentration in air
measurements) rather than with synthetic random data.</p>
<p>Ideas for tutorials (these capture the types of things that make sense, they’re
not necessarily the exact topics we propose to implement):</p>
<ul class="simple">
<li><p>Conway’s game of life with only NumPy (note: already in <a class="reference external" href="https://www.labri.fr/perso/nrougier/from-python-to-numpy/#the-game-of-life">Nicolas Rougier’s book</a>)</p></li>
<li><p>Using masked arrays to deal with missing data in time series measurements</p></li>
<li><p>Using Fourier transforms to analyze the Keeling curve data, and extrapolate it.</p></li>
<li><p>Geospatial data (e.g. lat/lon/time to create maps for every year via a stacked
array, like <a class="reference external" href="http://www.climatologylab.org/gridmet.html">gridMet data</a>)</p></li>
<li><p>Using text data and dtypes (e.g. use speeches from different people, shape
<code class="docutils literal notranslate"><span class="pre">(n_speech,</span> <span class="pre">n_sentences,</span> <span class="pre">n_words)</span></code>)</p></li>
</ul>
<p>The <em>Preparing to Teach</em> document <a class="footnote-reference brackets" href="#id6" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a> from the Software Carpentry Instructor
Training materials is a nice summary of how to write effective lesson plans (and
tutorials would be very similar). In addition to adding new tutorials, we also
propose a <em>How to write a tutorial</em> document, which would help users contribute
new high-quality content to the documentation.</p>
<section id="data-sets">
<h5>Data sets<a class="headerlink" href="#data-sets" title="Link to this heading">#</a></h5>
<p>Using interesting data in the NumPy docs requires giving all users access to
that data, either inside NumPy or in a separate package. The former is not the
best idea, since it’s hard to do without increasing the size of NumPy
significantly.</p>
<p>Whenever possible, documentation pages should use examples from the
<a class="reference external" href="https://docs.scipy.org/doc/scipy/reference/datasets.html#module-scipy.datasets" title="(in SciPy v1.15.3)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">scipy.datasets</span></code></a> package.</p>
</section>
</section>
</section>
</section>
<section id="related-work">
<h2>Related work<a class="headerlink" href="#related-work" title="Link to this heading">#</a></h2>
<p>Some examples of documentation organization in other projects:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://jupyter.org/documentation">Documentation for Jupyter</a></p></li>
<li><p><a class="reference external" href="https://docs.python.org/3/">Documentation for Python</a></p></li>
<li><p><a class="reference external" href="https://www.tensorflow.org/learn">Documentation for TensorFlow</a></p></li>
</ul>
<p>These projects make the intended audience for each part of the documentation
more explicit, as well as previewing some of the content in each section.</p>
</section>
<section id="implementation">
<h2>Implementation<a class="headerlink" href="#implementation" title="Link to this heading">#</a></h2>
<p>Currently, the <a class="reference external" href="https://numpy.org/devdocs/">documentation for NumPy</a> can be
confusing, especially for beginners. Our proposal is to reorganize the docs in
the following structure:</p>
<ul class="simple">
<li><dl class="simple">
<dt>For users:</dt><dd><ul>
<li><p>Absolute Beginners Tutorial</p></li>
<li><p>main Tutorials section</p></li>
<li><p>How Tos for common tasks with NumPy</p></li>
<li><p>Reference Guide (API Reference)</p></li>
<li><p>Explanations</p></li>
<li><p>F2Py Guide</p></li>
<li><p>Glossary</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>For developers/contributors:</dt><dd><ul>
<li><p>Contributor’s Guide</p></li>
<li><p>Under-the-hood docs</p></li>
<li><p>Building and extending the documentation</p></li>
<li><p>Benchmarking</p></li>
<li><p>NumPy Enhancement Proposals</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Meta information</dt><dd><ul>
<li><p>Reporting bugs</p></li>
<li><p>Release Notes</p></li>
<li><p>About NumPy</p></li>
<li><p>License</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
<section id="ideas-for-follow-up">
<h3>Ideas for follow-up<a class="headerlink" href="#ideas-for-follow-up" title="Link to this heading">#</a></h3>
<p>Besides rewriting the current documentation to some extent, it would be ideal
to have a technical infrastructure that would allow more contributions from the
community. For example, if Jupyter Notebooks could be submitted as-is as
tutorials or How-Tos, this might create more contributors and broaden the NumPy
community.</p>
<p>Similarly, if people could download some of the documentation in Notebook
format, this would certainly mean people would use less outdated material for
learning NumPy.</p>
<p>It would also be interesting if the new structure for the documentation makes
translations easier.</p>
</section>
</section>
<section id="discussion">
<h2>Discussion<a class="headerlink" href="#discussion" title="Link to this heading">#</a></h2>
<p>Discussion around this NEP can be found on the NumPy mailing list:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://mail.python.org/pipermail/numpy-discussion/2020-February/080419.html">https://mail.python.org/pipermail/numpy-discussion/2020-February/080419.html</a></p></li>
</ul>
</section>
<section id="references-and-footnotes">
<h2>References and footnotes<a class="headerlink" href="#references-and-footnotes" title="Link to this heading">#</a></h2>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id5" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>)</span>
<p><a class="reference external" href="https://diataxis.fr/">Diátaxis - A systematic framework for technical documentation authoring</a></p>
</aside>
<aside class="footnote brackets" id="id6" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">2</a><span class="fn-bracket">]</span></span>
<p><a class="reference external" href="https://carpentries.github.io/instructor-training/15-lesson-study/index.html">Preparing to Teach</a> (from the <a class="reference external" href="https://software-carpentry.org/">Software Carpentry</a> Instructor Training materials)</p>
</aside>
<aside class="footnote brackets" id="id7" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">3</a><span class="fn-bracket">]</span></span>
<p><a class="reference external" href="https://numpy.org/devdocs/user/absolute_beginners.html">NumPy for absolute beginners Tutorial</a> by Anne Bonner</p>
</aside>
</aside>
</section>
<section id="copyright">
<h2>Copyright<a class="headerlink" href="#copyright" title="Link to this heading">#</a></h2>
<p>This document has been placed in the public domain.</p>
</section>
</section>


                </article>
              
              
            </div>
            
            
                <dialog id="pst-secondary-sidebar-modal"></dialog>
                <div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#abstract">Abstract</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#motivation-and-scope">Motivation and scope</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#usage-and-impact">Usage and impact</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#backward-compatibility">Backward compatibility</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#detailed-description">Detailed description</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#status-and-ideas-of-each-type-of-doc-content">Status and ideas of each type of doc content</a><ul class="nav section-nav flex-column">
<li class="toc-h4 nav-item toc-entry"><a class="reference internal nav-link" href="#reference-guide">Reference guide</a></li>
<li class="toc-h4 nav-item toc-entry"><a class="reference internal nav-link" href="#how-to-guides">How-to guides</a></li>
<li class="toc-h4 nav-item toc-entry"><a class="reference internal nav-link" href="#explanations">Explanations</a></li>
<li class="toc-h4 nav-item toc-entry"><a class="reference internal nav-link" href="#tutorials">Tutorials</a><ul class="nav section-nav flex-column">
<li class="toc-h5 nav-item toc-entry"><a class="reference internal nav-link" href="#data-sets">Data sets</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#related-work">Related work</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#implementation">Implementation</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ideas-for-follow-up">Ideas for follow-up</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#discussion">Discussion</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#references-and-footnotes">References and footnotes</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#copyright">Copyright</a></li>
</ul>
  </nav></div>

</div></div>
              
            
          </div>
          <footer class="bd-footer-content">
            
          </footer>
        
      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script defer src="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></script>

  <footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
  
    <div class="footer-items__start">
      
        <div class="footer-item">

  <p class="copyright">
    
      © Copyright 2017-2025, NumPy Developers.
      <br/>
    
  </p>
</div>
      
        <div class="footer-item">

  <p class="sphinx-version">
    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
    <br/>
  </p>
</div>
      
    </div>
  
  
    <div class="footer-items__end">
      
        <div class="footer-item">
<p class="theme-version">
  <!-- # L10n: Setting the PST URL as an argument as this does not need to be localized -->
  Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.16.1.
</p></div>
      
    </div>
  
</div>

  </footer>
  </body>
</html>