{ "__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:adding_notebooks", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Under the " }, { "__type": "InlineCode", "__tag": 4051, "value": "doc/source/" }, { "__type": "Text", "__tag": 4046, "value": " folder of the SciPy tree you can find a few documents written in MyST Markdown format. The content in these files is executed when the SciPy documentation is built (locally or on CI) and any outputs generated by the execution are rendered in the final HTML files. In addition, they can be made interactive in the SciPy documentation website by using the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "jupyterlite-sphinx" } ], "url": "https://jupyterlite-sphinx.readthedocs.io/en/stable/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " extension." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you have a document written in Jupyter notebook format (an " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ipynb" }, { "__type": "Text", "__tag": 4046, "value": " file) and would like to submit it as part of the SciPy documentation, there are two options: you can convert it into a MyST Markdown file, and work with a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": " file only, or you can pair your " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ipynb" }, { "__type": "Text", "__tag": 4046, "value": " file with a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": " file and work with both. Note that " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ipynb" }, { "__type": "Text", "__tag": 4046, "value": " files " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "should not" } ] }, { "__type": "Text", "__tag": 4046, "value": " be submitted to the SciPy documentation." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In this document, we address conversion to a MyST Markdown file. For more information about MyST-NB, Jupytext and pairing notebooks, you can also consult the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pairing tutorial on NumPy Tutorials" } ], "url": "https://numpy.org/numpy-tutorials/content/pairing.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ". For even more information, please consult the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "MyST-NB documentation" } ], "url": "https://myst-nb.readthedocs.io/en/stable/authoring/text-notebooks.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Adding or editing tutorials as Jupyter notebooks" } ], "level": 0, "target": "adding-notebooks" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you don't need to keep the " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ipynb" }, { "__type": "Text", "__tag": 4046, "value": " file, and want to work with MyST Markdown only, follow the steps below." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Install the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "jupytext" } ], "url": "https://jupytext.readthedocs.io", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " tool, using " }, { "__type": "InlineCode", "__tag": 4051, "value": "pip install jupytext" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "conda install jupytext -c conda-forge" }, { "__type": "Text", "__tag": 4046, "value": ";" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "On your terminal, run " }, { "__type": "InlineCode", "__tag": 4051, "value": "jupytext notebook.ipynb --to myst" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "notebook.ipynb" }, { "__type": "Text", "__tag": 4046, "value": " should be replaced with the file you want to convert." } ] } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "jupytext" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now, the resulting " }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": " file (in MyST Markdown format) should contain a preamble similar to the one below, indicating that its contents will be executed when the SciPy documentation is built:" } ] }, { "__type": "Code", "__tag": 4050, "value": "---\njupytext:\n text_representation:\n extension: .md\n format_name: myst\n format_version: 0.13\n jupytext_version: 1.14.0\nkernelspec:\n display_name: Python 3 (ipykernel)\n language: python\n name: python3\n---", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You don't need to edit this preamble, as it is autogenerated." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "How to convert a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ipynb" }, { "__type": "Text", "__tag": 4046, "value": " file to a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": " file" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When converting a notebook to a MyST Markdown file, you may need to adjust some of the content to match the MyST Markdown syntax." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "External links:" } ] }, { "__type": "Text", "__tag": 4046, "value": " MyST Markdown uses the standard Markdown syntax for links. For example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "[link text](https://www.example.com)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Internal links:" } ] }, { "__type": "Text", "__tag": 4046, "value": " For internal cross-references such as links to SciPy classes or functions, as well as intersphinx links, you can use the following syntax: " }, { "__type": "InlineCode", "__tag": 4051, "value": "{role}`link text `" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "role" }, { "__type": "Text", "__tag": 4046, "value": " can be " }, { "__type": "InlineCode", "__tag": 4051, "value": "ref" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "class" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "func" }, { "__type": "Text", "__tag": 4046, "value": " or any other role you would use with reST. For example, to link to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy.stats.bartlett" }, { "__type": "Text", "__tag": 4046, "value": " function, use " }, { "__type": "InlineCode", "__tag": 4051, "value": "{func}`scipy.stats.bartlett`" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Formatting:" } ] }, { "__type": "Text", "__tag": 4046, "value": " MyST Markdown supports standard Markdown formatting, such as bold text, italic text, and code blocks. For example, to make text bold, you can use double asterisks: " }, { "__type": "InlineCode", "__tag": 4051, "value": "**bold text**" }, { "__type": "Text", "__tag": 4046, "value": ". To make text monospace/formatted as code, you can use " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "single" } ] }, { "__type": "Text", "__tag": 4046, "value": " backticks: " }, { "__type": "InlineCode", "__tag": 4051, "value": "`code`" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Images:" } ] }, { "__type": "Text", "__tag": 4046, "value": " If your notebook contains static images, you can include them in the MyST Markdown file by using the following syntax: " }, { "__type": "InlineCode", "__tag": 4051, "value": "![alt text](path/to/image.png)" }, { "__type": "Text", "__tag": 4046, "value": ". Images are usually stored in the same folder as the MyST Markdown file, but you can also use relative paths to reference images in other folders. Note that outputs of executed cells should not be included in version control, as they will be automatically generated when the notebook is executed during the SciPy documentation build." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Linking to the MyST Markdown pages:" } ] }, { "__type": "Text", "__tag": 4046, "value": " MyST Markdown supports adding link anchors, which can be used to link to specific pages or document sections from other documents. To add an anchor to a page, add " }, { "__type": "InlineCode", "__tag": 4051, "value": "(anchor_name)=" }, { "__type": "Text", "__tag": 4046, "value": " to the desired place in the document to be referenced. From other markdown pages, you can link to this anchor using the following syntax: " }, { "__type": "InlineCode", "__tag": 4051, "value": "{ref}`anchor_name`" }, { "__type": "Text", "__tag": 4046, "value": ". From other reST pages, you can link to this anchor using the following syntax: " }, { "__type": "InlineCode", "__tag": 4051, "value": ":ref:`anchor_name`" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Links, formatting and images" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you want to enable interactivity for your notebook when it is rendered in the SciPy documentation website, you need to add the following snippet at the beginning of the markdown file:" } ] }, { "__type": "Code", "__tag": 4050, "value": "```{eval-rst}\n.. notebooklite:: .md\n :new_tab: True\n```", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": " should be replaced with the name of the file you are working with. This will create a button that allows users to open the notebook in a new tab and interact with it. See " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Bartlett's test for equal variances" } ], "url": "https://scipy.github.io/devdocs/tutorial/stats/hypothesis_bartlett.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " (and " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "its source" } ], "url": "https://github.com/scipy/scipy/blob/main/doc/source/tutorial/stats/hypothesis_bartlett.md?plain=1", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ") for an example." } ] }, { "__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": "For simplicity, we don't want certain notebook cells to be visible in the rendered documentation. We can hide them by adding " }, { "__type": "InlineCode", "__tag": 4051, "value": "\"jupyterlite_sphinx_strip\"" }, { "__type": "Text", "__tag": 4046, "value": " to the tags section of the corresponding cell metadata. To do that in the Markdown file, add the following snippet right before the cell you want to hide:" } ] }, { "__type": "Code", "__tag": 4050, "value": "+++ {\"tags\": [\"jupyterlite_sphinx_strip\"]}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the " }, { "__type": "InlineRole", "__tag": 4003, "value": "+++", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " notation should come in pairs, surrounding the cell you want to hide." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Visit the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "NotebookLite directive documentation" } ], "url": "https://jupyterlite-sphinx.readthedocs.io/en/stable/directives/notebooklite.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " for more details and options." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Making the notebook interactive" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you have the " }, { "__type": "InlineCode", "__tag": 4051, "value": "jupytext" }, { "__type": "Text", "__tag": 4046, "value": " tool installed, you can open MyST Markdown " }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": " files in the Jupyter Notebook application and execute them, just as you would with a " }, { "__type": "InlineCode", "__tag": 4051, "value": ".ipynb" }, { "__type": "Text", "__tag": 4046, "value": " file." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Opening MyST Markdown files in the Jupyter Notebook application" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To convert a reStructuredText (" }, { "__type": "InlineCode", "__tag": 4051, "value": ".rst" }, { "__type": "Text", "__tag": 4046, "value": ") file to MyST Markdown (" }, { "__type": "InlineCode", "__tag": 4051, "value": ".md" }, { "__type": "Text", "__tag": 4046, "value": "), you can follow the formatting instructions above. You can also use tools such as " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "RST-to-MyST" } ], "url": "https://rst-to-myst.readthedocs.io", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " to automate the conversion, but please note some review may be necessary to ensure the conversion is correct. In particular, some reStructuredText directives may need to be wrapped in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "{eval-rst}" }, { "__type": "Text", "__tag": 4046, "value": " MyST directive, as follows " } ] }, { "__type": "Code", "__tag": 4050, "value": "Some Markdown here\n\n```{eval-rst}\n.. some_rest_directive_here::\n :some_option: some_value\n```\n\nSome more Markdown here", "execution_status": null }, { "__type": "Target", "__tag": 4061, "label": "MyST-NB" } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Converting " }, { "__type": "InlineCode", "__tag": 4051, "value": ".rst" }, { "__type": "Text", "__tag": 4046, "value": " files to MyST Markdown" } ], "level": 1, "target": null } ], "local_refs": [] }