{"cells":[{"cell_type":"markdown","id":"f548e7e8","metadata":{"id":"f548e7e8"},"source":["# Adding alert boxes to Jupyter notebooks\n","\n"," * Creator(s): Chris Slocum\n"," * Affiliation: NOAA Center for Satellite Applications and Research\n"," * History:\n","     * 2 July 2024 — initial version\n","\n","---\n","\n","\n","## Overview\n","The NOAA Center for Artificial Intelligence desires to create notebooks that use plain language. Part of plain language is to keep material short and organized using short lists, bullets, and other technical writing strategies. In notebooks, alert boxes aid in making material more engaging.\n","\n","### Prerequisite\n","To successfully complete this notebook, a basic understanding of the following is helpful, but not necessary.\n","* Markdown syntax\n","\n","### Learning Outcome\n","\n","* Adding alert boxes to Jupyter notebooks\n","\n","---"]},{"cell_type":"markdown","id":"17cee094","metadata":{"id":"17cee094"},"source":["## Using alert boxes in NCAI Learning Journey notebooks\n","\n","NCAI encourages notebook developers to consider adding engaging content while writing throughout their notebook material. Engaging content can include\n","* using headers to break up sections,\n","* adding bulleted lists,\n","* embedding relevant graphics and explanatory schematics,\n","* providing tips and warnings, and\n","* incorporating exercises.\n","\n","Breaking up the material helps keep the notebook interesting, provides structure to make finding material easier, and follows practices suggested by plain language initiatives.\n","\n","Markdown provides the syntax for stylizing text containing cells in Jupyter notebooks. The Markdown syntax allows developers to add HTML in addition to the native syntax. Many notebook rendering services such as Jupyter NBViewer support the [Bootstrap 3 Alerts](https://getbootstrap.com/docs/5.3/components/alerts/#examples) class style when used with the HTML `<div>` division or a section tag.\n","\n","The [Bootstrap 3 Alerts](https://getbootstrap.com/docs/5.3/components/alerts/#examples) Alerts class offers four stylized alert messages: 1. success, 2. info, 3. warning, and 4. danger. Most rendering services assign green, blue, yellow, and red, respectively, to each class.\n","\n","For use in NCAI Learning Journey notebooks, the NCAI Training and Workforce Development Team assigns the following meanings and uses for each box.\n","\n","* <font color='#0d5295'><b>Blue (alert-info)</b></font>: Use blue 'info' boxes for tips, hints, notes, and other useful information.\n","* <font color='#bf9002'><b>Yellow (alert-warning)</b></font>: Use yellow 'warning' boxes to warn explorers about potential data or machine learning technique specific issues that do not qualify as a tip.\n","* <font color='#38751e'><b>Green (alert-success)</b></font>: Use green 'success' boxes for optional exercises for explorers.\n","* <font color='#cc0000'><b>Red (alert-danger)</b></font>: Use red 'Danger' boxes to convey potential errors that explorers may encounter (typically for missing packages or package version compatibility). NCAI discourages using the danger box and expects developers to use them sparingly.\n","\n","Below is the code and an example of each box. Note that we also include a heading for each of the alert boxes as some rendering services (e.g., Google Colab) currently lack support for the [Bootstrap 3 Alerts](https://getbootstrap.com/docs/5.3/components/alerts/#examples) class.\n","\n"]},{"cell_type":"markdown","id":"b374686c","metadata":{"vscode":{"languageId":"plaintext"},"id":"b374686c"},"source":["### Info alert box\n","<div class=\"alert alert-block alert-info\">\n","    <h3>Tip</h3>\n","    Use blue 'info' boxes for tips, hints, notes, and other useful information.\n","</div>"]},{"cell_type":"raw","id":"6b52dfa5","metadata":{"id":"6b52dfa5"},"source":["<div class=\"alert alert-block alert-info\">\n","    <h3>Tip</h3>\n","    Use blue 'info' boxes for tips, hints, notes, and other useful information.\n","</div>"]},{"cell_type":"markdown","id":"61623c53","metadata":{"id":"61623c53"},"source":["### Warning alert box\n","<div class=\"alert alert-block alert-warning\">\n","    <h3>Warning</h3>\n","    Use yellow ‘warning’ boxes to warn explorers about potential data or machine learning technique specific issues that do not qualify as a tip.\n","</div>"]},{"cell_type":"raw","id":"cfaf0b5f","metadata":{"id":"cfaf0b5f"},"source":["<div class=\"alert alert-block alert-warning\">\n","    <h3>Warning</h3>\n","    Use yellow ‘warning’ boxes to warn explorers about potential data or machine learning technique specific issues that do not qualify as a tip.\n","</div>"]},{"cell_type":"markdown","id":"05cb9bf2","metadata":{"id":"05cb9bf2"},"source":["### Exercise alert box\n","<div class=\"alert alert-block alert-success\">\n","    <h3>Exercise</h3>\n","    Use green ''success'' boxes for optional exercises for explorers.\n","</div>"]},{"cell_type":"raw","id":"882a6da9","metadata":{"id":"882a6da9"},"source":["<div class=\"alert alert-block alert-success\">\n","    <h3>Exercise</h3>\n","    Use green ''success'' boxes for optional exercises for explorers.\n","</div>"]},{"cell_type":"markdown","id":"6bbea20c","metadata":{"id":"6bbea20c"},"source":["### Danger alert box\n","<div class=\"alert alert-block alert-danger\">\n","    <h3>Danger</h3>\n","    Use red ‘Danger’ boxes to convey potential errors that explorers may encounter (typically for missing packages or package version compatibility).\n","</div>"]},{"cell_type":"raw","id":"ac38cff4","metadata":{"id":"ac38cff4"},"source":["<div class=\"alert alert-block alert-danger\">\n","    <h3>Danger</h3>\n","    Use red ‘Danger’ boxes to convey potential errors that explorers may encounter (typically for missing packages or package version compatibility).\n","</div>"]},{"cell_type":"markdown","id":"5b4d0e34","metadata":{"id":"5b4d0e34"},"source":["## References\n","* Python, 2023: The Python Standard Library. Accessed 4 April 2023, [https://docs.python.org/3/library/index.html](https://docs.python.org/3/library/index.html).\n","\n","## Metadata\n","* Language / package(s): Python / Markdown\n","* Domain: general, training\n","* Application keywords: notebooks\n","* Geophysical keywords: N/A\n","* AI keywords: N/A\n","\n","## Disclaimer\n","This Jupyter notebook is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA Jupyter notebooks are provided on an 'as is' basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this Jupyter notebook will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government."]},{"cell_type":"code","execution_count":null,"id":"52a7e334","metadata":{"id":"52a7e334"},"outputs":[],"source":[]}],"metadata":{"kernelspec":{"display_name":"Python 3 (ipykernel)","language":"python","name":"python3"},"language_info":{"codemirror_mode":{"name":"ipython","version":3},"file_extension":".py","mimetype":"text/x-python","name":"python","nbconvert_exporter":"python","pygments_lexer":"ipython3","version":"3.9.5"},"colab":{"provenance":[]}},"nbformat":4,"nbformat_minor":5}