{ "__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:contributor:rendering_documentation", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We're eager to hear about and fix doc defects. But to attack the biggest problems we end up having to defer or overlook some bug reports. Here are the best defects to go after." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Top priority goes to " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "technical inaccuracies" } ] }, { "__type": "Text", "__tag": 4046, "value": " – a docstring missing a parameter, a faulty description of a function/parameter/method, and so on. Other “structural” defects like broken links also get priority. All these fixes are easy to confirm and put in place. You can " }, { "__type": "InlineRole", "__tag": 4003, "value": "submit a pull request (PR)", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " with the fix, if you know how to do that; otherwise please " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "open an issue" } ], "url": "https://github.com/scipy/scipy/issues/new/choose", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Typos and misspellings" } ] }, { "__type": "Text", "__tag": 4046, "value": " fall on a lower rung; we welcome hearing about them but may not be able to fix them promptly. These too can be handled as pull requests or issues." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Obvious " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "wording" } ] }, { "__type": "Text", "__tag": 4046, "value": " mistakes (like leaving out a “not”) fall into the typo category, but other rewordings – even for grammar – require a judgment call, which raises the bar. One can imagine cases where it is not clear that a \"fix\" should be made, e.g.:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Attempting to \"fix\" all the uses (or lack thereof) of the Oxford comma." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Cases where the correctness of common usage is evolving, e.g. \"comprised of\"" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The easiest fixes to accept are those where the original version is clearly and unambiguously wrong; changes that require subtle editorial judgement are probably best avoided. (But note that this is not about updating documentation to fix confusing statements or otherwise deal with documentation problems reported by users.)" } ] }, { "__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": "As a general guideline, try to accumulate small documentation changes (such as typos) instead of sending them one by one. Whenever possible, also make sure to use the correct commands to " }, { "__type": "CrossRef", "__tag": 4002, "value": "skip CI checks", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:contributor:continuous_integration" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " on documentation changes." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some functions/objects defined in C or Fortran extension modules have their docstrings defined separately from the actual code. Make sure to do a search for the function docstring you are looking for using either " }, { "__type": "InlineRole", "__tag": 4003, "value": "grep", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " or other similar tools." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Contributing to the SciPy documentation" } ], "level": 0, "target": "contributing-docs" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SciPy docstrings are rendered to HTML using " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sphinx" } ], "url": "http://www.sphinx-doc.org/en/master/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " and the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "PyData Sphinx theme" } ], "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ". Writing docstrings is covered in the " }, { "__type": "InlineRole", "__tag": 4003, "value": "numpy:howto-document", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "; this document explains how to check that docstrings render properly." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a video walkthrough, please see" } ] }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Rendering SciPy Documentation with Sphinx" } ], "url": "https://youtu.be/kGSYU39EhJQ", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To render the documentation on your own machine:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Ensure that you have a working SciPy build (see " }, { "__type": "CrossRef", "__tag": 4002, "value": "building-from-source", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "building:index" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Then run " }, { "__type": "InlineCode", "__tag": 4051, "value": "spin docs" }, { "__type": "Text", "__tag": 4046, "value": " to build the documentation. This can take a while the first time, but subsequent documentation builds are typically much faster." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "View the documentation in " }, { "__type": "InlineCode", "__tag": 4051, "value": "doc/build/html/" }, { "__type": "Text", "__tag": 4046, "value": ". You can start with " }, { "__type": "InlineCode", "__tag": 4051, "value": "index.html" }, { "__type": "Text", "__tag": 4046, "value": " and browse, or you can jump straight to the file you’re interested in." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Changes to certain documents do not take effect when Sphinx documentation is rebuilt. In this case, you can build from scratch by deleting the directories " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy/doc/build" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "source/reference/generated" }, { "__type": "Text", "__tag": 4046, "value": ", or by running " }, { "__type": "InlineCode", "__tag": 4051, "value": "spin docs clean" }, { "__type": "Text", "__tag": 4046, "value": " then building the docs again." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In case the SciPy version found by the above command is different from that of the latest commit in the repo, you will see a message like " } ] }, { "__type": "Code", "__tag": 4050, "value": "installed scipy 5fd20ec1aa != current repo git version '35fd20ec1a'", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This indicates that you're likely picking up the wrong SciPy install, check with " }, { "__type": "InlineCode", "__tag": 4051, "value": "python -c \"import scipy; print(scipy.__file__)\"" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The SciPy documentation contains interactive examples rendered with the help of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "jupyterlite-sphinx" }, { "__type": "Text", "__tag": 4046, "value": " extension. For more details, see " }, { "__type": "CrossRef", "__tag": 4002, "value": "adding-notebooks", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:contributor:adding_notebooks" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "interactive-docs", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Rendering documentation locally with Sphinx" } ], "level": 1, "target": "rendering-documentation" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Once a PR is opened, you can check that documentation renders correctly on the cloud." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Log in to " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "GitHub" } ], "url": "https://github.com/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Log in " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "CircleCI" } ], "url": "https://circleci.com/vcs-authorize/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " using your GitHub account." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Back in GitHub, at the bottom of the PR, select “Show all Checks”." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Next to “Check the rendered docs here!”, select “Details”." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Checking Documentation on the Cloud" } ], "level": 1, "target": "rendering-documentation-cloud" }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Documentation Guidelines" } ], "level": 1, "target": "docs-guidelines" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When specifying a required condition on the input parameters, the word \"must\" is preferable to \"should\". For many English speakers, \"must\" implies a stronger constraint than \"should\", e.g. \"I must have oxygen to live\" versus \"I should exercise more\"." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": "Parameters\n----------\nx : float\n `x` must be nonnegative.", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No " } ] }, { "__type": "Code", "__tag": 4050, "value": "Parameters\n----------\nx : float\n `x` should be nonnegative.", "execution_status": null } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Use \"must\", not \"should\"" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a new function, the 'versionadded' markup goes in the \"Notes\" section, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "not" } ] }, { "__type": "Text", "__tag": 4046, "value": " in the description at the beginning of the docstring." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a new argument added to an existing function, the 'versionadded' markup is placed at the end of the description of the argument in the \"Parameters\" section." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Use of the 'versionadded' markup" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is acceptable to use wikipedia articles as references. When creating the citation for the reference, include the article title, the name \"Wikipedia\" (similar to how one gives a journal title), and the URL." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": ".. [1] \"Zeta Distribution\", Wikipedia,\n https://en.wikipedia.org/wiki/Zeta_distribution", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No " } ] }, { "__type": "Code", "__tag": 4050, "value": ".. [1] https://en.wikipedia.org/wiki/Zeta_distribution", "execution_status": null } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Citing wikipedia articles in the \"References\" section" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The use of DOIs in references is strongly recommended. There is special Sphinx syntax for DOIs: " }, { "__type": "InlineCode", "__tag": 4051, "value": ":doi:" }, { "__type": "Text", "__tag": 4046, "value": ". For example " } ] }, { "__type": "Code", "__tag": 4050, "value": ".. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,\n C. Priebe, \"Seeded graph matching\", Pattern Recognit. 87 (2019):\n 203-215, :doi:`10.1016/j.patcog.2018.09.014`", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "(arXiv articles also have special markup available: " }, { "__type": "InlineCode", "__tag": 4051, "value": ":arxiv:" }, { "__type": "Text", "__tag": 4046, "value": ".)" } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "DOIs in references" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is not so much a guideline as it is a reminder of the Sphinx markup for bulleted lists. The incorrect use of indentation is common enough that it is worthwhile mentioning it here." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When creating a bulleted list:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Don't end the preceding line with " }, { "__type": "InlineRole", "__tag": 4003, "value": "::", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Don't indent the bullets." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Include a blank line before and after the list." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some examples:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": "Some text that precedes this interesting list:\n\n* The first item in the list.\n* The second item in the list.\n* You get the idea.\n\nSome text that follows the list.", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No " } ] }, { "__type": "Code", "__tag": 4050, "value": "Some text that precedes this interesting list:\n\n * The first item in the list.\n * The second item in the list.\n * You get the idea.\n\nSome text that follows the list.", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No " } ] }, { "__type": "Code", "__tag": 4050, "value": "Some text that precedes this interesting list:\n* The first item in the list.\n* The second item in the list.\n* You get the idea.\nSome text that follows the list.", "execution_status": null } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Bulleted lists" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Each \"Example\" section (both in docstrings and general documentation) must be self-contained. This means that all imports must be explicit, the data used must be defined, and the code should \"just work\" when copy-pasted into a fresh Python interpreter." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> rng = np.random.default_rng()", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> rng = np.random.default_rng()", "execution_status": null } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "What is possible (and recommended) is to intersperse blocks of code with explanations. Blank lines must separate each code block from the explanatory text." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": "Some initial text\n\n>>> import numpy as np\n>>> rng = np.random.default_rng()\n\nThis is some explanation\n\n>>> rng.random(10)", "execution_status": null } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Self-contained examples" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the continuous integration (CI) suite, examples are executed and the output is compared against the provided reference. The main goal is to ensure that the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "example" } ] }, { "__type": "Text", "__tag": 4046, "value": " is correct; a failure warns us that the example may need to be adjusted (e.g. because the API has changed since it was written). Doctests are not meant to be used as unit tests of underlying implementation." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In case a random number generator is needed, " }, { "__type": "InlineRole", "__tag": 4003, "value": "np.random.Generator", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " must be used. The canonical way to create a NumPy " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": " is to use " }, { "__type": "InlineRole", "__tag": 4003, "value": "np.random.default_rng", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> rng = np.random.default_rng()\n>>> sample = rng.random(10)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Yes " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> rng = np.random.default_rng(102524723947864966825913730119128190984)\n>>> sample = rng.random(10)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> sample = np.random.random(10)", "execution_status": null } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Seeding the generator object is optional. If a seed is used, avoid common numbers and instead generate a seed with " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.random.SeedSequence().entropy" }, { "__type": "Text", "__tag": 4046, "value": ". If no seed is provided, the default value " }, { "__type": "InlineCode", "__tag": 4051, "value": "1638083107694713882823079058616272161" }, { "__type": "Text", "__tag": 4046, "value": " is used when doctests are executed. In either case, the rendered documentation will not show the seed. The intent is to discourage users from copy/pasting seeds in their code and instead make an explicit decision about the use of a seed in their program. The consequence is that users cannot reproduce the results of the example exactly, so examples using random data should not refer to precise numerical values based on random data or rely on them to make their point." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Examples and randomness" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a function, module or API is in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "legacy" } ] }, { "__type": "Text", "__tag": 4046, "value": " mode, meaning that it is kept around for backwards compatibility reasons, but is not recommended to use in new code, you can use the " }, { "__type": "InlineCode", "__tag": 4051, "value": ".. legacy::" }, { "__type": "Text", "__tag": 4046, "value": " directive." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By default, if used with no arguments, the legacy directive will generate the following output:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We strongly recommend that you also add a custom message, such as a new API to replace the old one. This message will be appended to the default message " } ] }, { "__type": "Code", "__tag": 4050, "value": ".. legacy::\n\n New code should use :mod:`scipy.fft`.", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "will create the following output:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Finally, if you want to mention a function, method (or any custom object) instead of a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "submodule" } ] }, { "__type": "Text", "__tag": 4046, "value": ", you can use an optional argument " } ] }, { "__type": "Code", "__tag": 4050, "value": ".. legacy:: function", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This will create the following output:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "---" } ] }, { "__type": "Target", "__tag": 4061, "label": "GitHub" }, { "__type": "Target", "__tag": 4061, "label": "CircleCI" }, { "__type": "Target", "__tag": 4061, "label": "Sphinx" }, { "__type": "Target", "__tag": 4061, "label": "PyData Sphinx theme" }, { "__type": "Target", "__tag": 4061, "label": "Sphinx-Design" }, { "__type": "Target", "__tag": 4061, "label": "numpydoc" }, { "__type": "Target", "__tag": 4061, "label": "matplotlib" }, { "__type": "Target", "__tag": 4061, "label": "Rendering SciPy Documentation with Sphinx" }, { "__type": "Target", "__tag": 4061, "label": "git submodules" }, { "__type": "Target", "__tag": 4061, "label": "Make build automation tool" } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Legacy directive" } ], "level": 2, "target": null } ], "local_refs": [] }