{
  "__type": "IngestedDoc",
  "__tag": 4010,
  "_content": {},
  "_ordered_sections": [],
  "item_file": null,
  "item_line": null,
  "item_type": null,
  "aliases": [],
  "example_section_data": {
    "__type": "Section",
    "__tag": 4015,
    "children": [],
    "title": [],
    "level": 0,
    "target": null
  },
  "see_also": [],
  "signature": null,
  "references": null,
  "qa": "dev:howto_build_docs",
  "arbitrary": [
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "If you only want to get the documentation, note that pre-built versions can be found at"
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "https://numpy.org/doc/"
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "in several different formats."
            }
          ]
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "Building the NumPy API and reference docs"
        }
      ],
      "level": 0,
      "target": "howto-build-docs"
    },
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Before proceeding further it should be noted that the documentation is built with the "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "make"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " tool, which is not natively available on Windows. MacOS or Linux users can jump to "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "how-todoc.prerequisites",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "dev:howto_build_docs"
              },
              "kind": "exists"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". It is recommended for Windows users to set up their development environment on GitHub Codespaces (see "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "recommended-development-setup",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "dev:development_environment"
              },
              "kind": "exists"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ") or "
            },
            {
              "__type": "Link",
              "__tag": 4049,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Windows Subsystem for Linux (WSL)"
                }
              ],
              "url": "https://learn.microsoft.com/en-us/windows/wsl/install",
              "title": ""
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". WSL is a good option for a persistent local set-up."
            }
          ]
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "Development environments"
        }
      ],
      "level": 1,
      "target": null
    },
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Building the NumPy documentation and API reference requires the following:"
            }
          ]
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "Prerequisites"
        }
      ],
      "level": 1,
      "target": "how-todoc.prerequisites"
    },
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Since large parts of the main documentation are obtained from NumPy via "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "import numpy"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " and examining the docstrings, you will need to first "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "build",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "dev:development_environment"
              },
              "kind": "exists"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " and install it so that the correct version is imported. NumPy has to be re-built and re-installed every time you fetch the latest version of the repository, before generating the documentation. This ensures that the NumPy version and the git repository version are in sync."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Note that you can e.g. install NumPy to a temporary location and set the PYTHONPATH environment variable appropriately. Alternatively, if using Python virtual environments (via e.g. "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "conda"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "virtualenv"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " or the "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "venv"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " module), installing NumPy into a new virtual environment is recommended."
            }
          ]
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "NumPy"
        }
      ],
      "level": 2,
      "target": null
    },
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "All of the necessary dependencies for building the NumPy docs except for "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "Doxygen",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "dev:howto_build_docs"
              },
              "kind": "exists"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " can be installed with      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "pip install -r requirements/doc_requirements.txt",
          "execution_status": null
        },
        {
          "__type": "Admonition",
          "__tag": 4056,
          "kind": "note",
          "base_type": "note",
          "children": [
            {
              "__type": "AdmonitionTitle",
              "__tag": 4055,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "note "
                }
              ]
            },
            {
              "__type": "Paragraph",
              "__tag": 4045,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "It may be necessary to install development versions of the doc dependencies to build the docs locally      "
                }
              ]
            },
            {
              "__type": "Code",
              "__tag": 4050,
              "value": "pip install --pre --force-reinstall --extra-index-url \\\nhttps://pypi.anaconda.org/scientific-python-nightly-wheels/simple \\\n-r requirements/doc_requirements.txt",
              "execution_status": null
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "We currently use "
            },
            {
              "__type": "Link",
              "__tag": 4049,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Sphinx"
                }
              ],
              "url": "https://www.sphinx-doc.org/",
              "title": ""
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " along with "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "Doxygen",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "dev:howto_build_docs"
              },
              "kind": "exists"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " for generating the API and reference documentation for NumPy. In addition, building the documentation requires the Sphinx extension "
            },
            {
              "__type": "InlineRole",
              "__tag": 4003,
              "value": "plot_directive",
              "domain": null,
              "role": null,
              "inventory": null
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", which is shipped with "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "Matplotlib",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "matplotlib:index"
              },
              "kind": "docs"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". We also use "
            },
            {
              "__type": "Link",
              "__tag": 4049,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "numpydoc"
                }
              ],
              "url": "https://github.com/numpy/numpydoc",
              "title": ""
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " to render docstrings in the generated API documentation. "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "SciPy",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "scipy:index"
              },
              "kind": "docs"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " is installed since some parts of the documentation require SciPy functions."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "For installing "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "Doxygen",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "docs",
                "path": "dev:howto_build_docs"
              },
              "kind": "exists"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", please check the official "
            },
            {
              "__type": "Link",
              "__tag": 4049,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "download"
                }
              ],
              "url": "https://www.doxygen.nl/download.html#srcbin",
              "title": ""
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " and "
            },
            {
              "__type": "Link",
              "__tag": 4049,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "installation"
                }
              ],
              "url": "https://www.doxygen.nl/manual/install.html",
              "title": ""
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " pages, or if you are using Linux then you can install it through your distribution package manager."
            }
          ]
        },
        {
          "__type": "Admonition",
          "__tag": 4056,
          "kind": "note",
          "base_type": "note",
          "children": [
            {
              "__type": "AdmonitionTitle",
              "__tag": 4055,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "note "
                }
              ]
            },
            {
              "__type": "Paragraph",
              "__tag": 4045,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Try to install a newer version of "
                },
                {
                  "__type": "CrossRef",
                  "__tag": 4002,
                  "value": "Doxygen",
                  "reference": {
                    "__type": "LocalRef",
                    "__tag": 4022,
                    "kind": "docs",
                    "path": "dev:howto_build_docs"
                  },
                  "kind": "exists"
                },
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": " > 1.8.10 otherwise you may get some warnings during the build."
                }
              ]
            }
          ]
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "Dependencies"
        }
      ],
      "level": 2,
      "target": null
    },
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "If you obtained NumPy via git, also get the git submodules that contain additional parts required for building the documentation      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "git submodule update --init",
          "execution_status": null
        },
        {
          "__type": "Target",
          "__tag": 4061,
          "label": "Sphinx"
        },
        {
          "__type": "Target",
          "__tag": 4061,
          "label": "numpydoc"
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "Submodules"
        }
      ],
      "level": 2,
      "target": null
    },
    {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Now you are ready to generate the docs, so write      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "spin docs",
          "execution_status": null
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "This will build NumPy from source if you haven't already, and run Sphinx to build the "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "html"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " docs. If all goes well, this will generate a "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "build/html"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " subdirectory in the "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "/doc"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " directory, containing the built documentation."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The documentation for NumPy distributed at https://numpy.org/doc in html and pdf format is also built with "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "make dist"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ".  See "
            },
            {
              "__type": "Link",
              "__tag": 4049,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "HOWTO RELEASE"
                }
              ],
              "url": "https://github.com/numpy/numpy/blob/main/doc/HOWTO_RELEASE.rst",
              "title": ""
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " for details on how to update https://numpy.org/doc."
            }
          ]
        },
        {
          "__type": "Target",
          "__tag": 4061,
          "label": "LaTeX"
        },
        {
          "__type": "Target",
          "__tag": 4061,
          "label": "HOWTO RELEASE"
        }
      ],
      "title": [
        {
          "__type": "Text",
          "__tag": 4046,
          "value": "Instructions"
        }
      ],
      "level": 1,
      "target": "Doxygen"
    }
  ],
  "local_refs": []
}