Update README, incl. image alt text

hugetim · Nov 5, 2024 · 25f187e · 25f187e
1 parent e82a201
commit 25f187e
Show file tree

Hide file tree

Showing 3 changed files with 70 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -3,6 +3,8 @@
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
+
+
 `nbstata` is a [Jupyter
 kernel](https://docs.jupyter.org/en/latest/projects/kernels.html) for
 [Stata](https://www.stata.com/why-use-stata/) built on top of
@@ -11,14 +13,13 @@ kernel](https://docs.jupyter.org/en/latest/projects/kernels.html) for
 **[*For the User Guide, click
 here.*](https://hugetim.github.io/nbstata/user_guide.html)**
 
+
+
 ## What is Jupyter?
 
-[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html)
-is a browser-based editor that allows you to combine interactive code
-and results with
-[Markdown](https://daringfireball.net/projects/markdown/basics) in a
-single document (called a Jupyter notebook). It is open source and
-widely used. Though it is named after the three core programming
+A Jupyter notebook allows you to combine interactive code and results
+with [Markdown](https://daringfireball.net/projects/markdown/basics) in
+a single document. Though it is named after the three core programming
 languages it supports (Julia, Python, and R), it can be used with with a
 wide variety of languages.
 
@@ -27,9 +28,7 @@ Stata within a *Python*
 notebook](https://www.stata.com/python/pystata18/notebook/Example2.html),
 which is needlessly clunky if you are working primarily with Stata).
 
-<img align="center" width="650" src="https://github.com/kylebarron/stata_kernel/raw/master/docs/src/img/jupyter_notebook_example.gif">
-
-### `nbstata` features
+### Key nbstata features
 
 - [x] [Easy
   setup](https://hugetim.github.io/nbstata/user_guide.html#install)
@@ -39,11 +38,13 @@ which is needlessly clunky if you are working primarily with Stata).
 - [x] Autocompletion for variables, macros, matrices, and file paths
 - [x] DataGrid widget with `browse`-like capabilities (e.g., interactive
   filtering)
-- [x] Variable and data properties (`describe` and `e`/`return list`)
-  available in a ‘contextual help’ side panel
+- [x] Variable and data properties available in a ‘contextual help’ side
+  panel
 - [x] Interactive/richtext help files accessible within notebook
 - [x] `#delimit ;` interactive support (along with all types of
   comments)
+- [x] Quarto [inline
+  code](https://quarto.org/docs/computations/inline-code.html) support
 
 ### What can you do with Stata notebooks…
 
@@ -52,28 +53,27 @@ interface](https://www.stata.com/features/overview/graphical-user-interface/)?
 
 - Exploratory analysis that is both:
   - interactive
-  - preserved for future reference/editing
-- Present results in a way that interweaves:\[1\]
+  - preserved for future reference/editing  
+- Present results in a way that interweaves:[^1]
   - code
   - results (including graphs)
   - rich text:
     1.  lists
     2.  **Headings**
-    3.  <img align="left" width="54" height="18.6" src="https://raw.githubusercontent.com/hugetim/nbstata/master/index_files/figure-commonmark/226326ec-1-image-2.png">
+    3.  <img align="left" width="54" height="18.6" src="https://raw.githubusercontent.com/hugetim/nbstata/master/index_files/figure-commonmark/226326ec-1-image-2.png" alt="WordArt of the word 'images'">
     4.  [links](https://hugetim.github.io/nbstata/)
     5.  math: $y_{it}=\beta_0+\varepsilon_{it}$
 
-\[1\] Stata [dynamic
-documents](https://www.stata.com/manuals/rptdynamicdocumentsintro.pdf)
-can do this part, though with a less interactive workflow. (See also:
-[markstat](https://grodri.github.io/markstat/),
-[stmd](https://www.ssc.wisc.edu/~hemken/Stataworkshops/stmd/Usage/stmdusage.html),
-and
-[Statamarkdown](https://ssc.wisc.edu/~hemken/Stataworkshops/Statamarkdown/stata-and-r-markdown.html))
-Using `nbstata` with
-[Quarto](https://www.statalist.org/forums/forum/general-stata-discussion/general/1703835-ado-files-and-literate-programming)
-instead gives you a similar workflow, with greater flexibility of
-output.
+The video below demonstrates using Stata in a Jupyter notebook. In
+addition to the
+[NBClassic](https://nbclassic.readthedocs.io/en/stable/notebook.html)
+application shown there, `nbstata` can also be used with
+[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html),
+[VS
+Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks),
+or [Quarto](https://quarto.org/).
+
+<img align="center" width="650" src="https://kylebarron.dev/stata_kernel/img/jupyter_notebook_example.gif" alt="Animated demo showing major Stata kernel features in a Jupyter notebook">
 
 ## Contributing
 
@@ -93,3 +93,15 @@ versions of Stata. Vinci Chow created a Stata kernel that instead uses
 available with Stata 17. `nbstata` was originally derived from his
 [pystata-kernel](https://github.com/ticoneva/pystata-kernel), but much
 of the docs and newer features are derived from `stata_kernel`.
+
+[^1]: Stata [dynamic
+    documents](https://www.stata.com/manuals/rptdynamicdocumentsintro.pdf)
+    can do this part, though with a less interactive workflow. (See
+    also: [markstat](https://grodri.github.io/markstat/),
+    [stmd](https://www.ssc.wisc.edu/~hemken/Stataworkshops/stmd/Usage/stmdusage.html),
+    and
+    [Statamarkdown](https://ssc.wisc.edu/~hemken/Stataworkshops/Statamarkdown/stata-and-r-markdown.html))
+    Using `nbstata` with
+    [Quarto](https://www.statalist.org/forums/forum/general-stata-discussion/general/1703835-ado-files-and-literate-programming)
+    instead gives you a similar workflow, with greater flexibility of
+    output.
diff --git a/nbs/custom.yml b/nbs/custom.yml
@@ -9,3 +9,6 @@ website:
     right:
       - icon: github
         href: "https://github.com/hugetim/nbstata"
+format:
+  html:  
+    reference-location: section
diff --git a/nbs/index.ipynb b/nbs/index.ipynb
@@ -13,14 +13,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "&nbsp;\n",
+    "\n",
     "`nbstata` is a [Jupyter kernel](https://docs.jupyter.org/en/latest/projects/kernels.html) for [Stata](https://www.stata.com/why-use-stata/) built on top of [pystata](https://www.stata.com/python/pystata18/index.html)."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "**[*For the User Guide, click here.*](https://hugetim.github.io/nbstata/user_guide.html)**"
+    "**[*For the User Guide, click here.*](https://hugetim.github.io/nbstata/user_guide.html)**\n",
+    "\n",
+    "&nbsp;"
    ]
   },
   {
@@ -34,27 +38,26 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html) is a browser-based editor that allows you to combine interactive code and results with [Markdown](https://daringfireball.net/projects/markdown/basics) in a single document (called a Jupyter notebook). It is open source and widely used. Though it is named after the three core programming languages it supports (Julia, Python, and R), it can be used with with a wide variety of languages. \n",
+    "A Jupyter notebook allows you to combine interactive code and results with [Markdown](https://daringfireball.net/projects/markdown/basics) in a single document. Though it is named after the three core programming languages it supports (Julia, Python, and R), it can be used with with a wide variety of languages. \n",
     "\n",
-    "`nbstata` allows you to create Stata notebooks (as opposed to [using Stata within a *Python* notebook](https://www.stata.com/python/pystata18/notebook/Example2.html), which is  needlessly clunky if you are working primarily with Stata).\n",
-    "\n",
-    "<img align=\"center\" width=\"650\" src=\"https://kylebarron.dev/stata_kernel/img/jupyter_notebook_example.gif\">"
+    "`nbstata` allows you to create Stata notebooks (as opposed to [using Stata within a *Python* notebook](https://www.stata.com/python/pystata18/notebook/Example2.html), which is needlessly clunky if you are working primarily with Stata)."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### `nbstata` features\n",
+    "### Key nbstata features\n",
     "\n",
     "- [x] [Easy setup](https://hugetim.github.io/nbstata/user_guide.html#install)\n",
     "- [x] Works with Stata 17+ (only).\n",
     "- [x] Displays Stata output without the redundant 'echo' of (multi-line) commands\n",
     "- [x] Autocompletion for variables, macros, matrices, and file paths\n",
     "- [x] DataGrid widget with `browse`-like capabilities (e.g., interactive filtering)\n",
-    "- [x] Variable and data properties (`describe` and `e`/`return list`) available in a 'contextual help' side panel\n",
+    "- [x] Variable and data properties available in a 'contextual help' side panel\n",
     "- [x] Interactive/richtext help files accessible within notebook\n",
-    "- [x] `#delimit ;` interactive support (along with all types of comments)"
+    "- [x] `#delimit ;` interactive support (along with all types of comments)\n",
+    "- [x] Quarto [inline code](https://quarto.org/docs/computations/inline-code.html) support"
    ]
   },
   {
@@ -67,18 +70,33 @@
     "* Exploratory analysis that is both:\n",
     "    * interactive\n",
     "    * preserved for future reference/editing\n",
-    "    \n",
-    "* Present results in a way that interweaves:[1]\n",
+    "&nbsp;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "* Present results in a way that interweaves:[^1]\n",
     "    * code\n",
     "    * results (including graphs)\n",
     "    * rich text: \n",
     "        1. lists\n",
     "        2. **Headings**\n",
-    "        3. <img align=\"left\" width=\"54\" height=\"18.6\" src=\"https://raw.githubusercontent.com/hugetim/nbstata/master/index_files/figure-commonmark/226326ec-1-image-2.png\">\n",
+    "        3. <img align=\"left\" width=\"54\" height=\"18.6\" src=\"https://raw.githubusercontent.com/hugetim/nbstata/master/index_files/figure-commonmark/226326ec-1-image-2.png\" alt=\"WordArt of the word 'images'\">\n",
     "        4. [links](https://hugetim.github.io/nbstata/) \n",
     "        5. math: $y_{it}=\\beta_0+\\varepsilon_{it}$\n",
     "\n",
-    "[1] Stata [dynamic documents](https://www.stata.com/manuals/rptdynamicdocumentsintro.pdf) can do this part, though with a less interactive workflow. (See also: [markstat](https://grodri.github.io/markstat/), [stmd](https://www.ssc.wisc.edu/~hemken/Stataworkshops/stmd/Usage/stmdusage.html), and [Statamarkdown](https://ssc.wisc.edu/~hemken/Stataworkshops/Statamarkdown/stata-and-r-markdown.html)) Using `nbstata` with [Quarto](https://www.statalist.org/forums/forum/general-stata-discussion/general/1703835-ado-files-and-literate-programming) instead gives you a similar workflow, with greater flexibility of output."
+    "[^1]: Stata [dynamic documents](https://www.stata.com/manuals/rptdynamicdocumentsintro.pdf) can do this part, though with a less interactive workflow. (See also: [markstat](https://grodri.github.io/markstat/), [stmd](https://www.ssc.wisc.edu/~hemken/Stataworkshops/stmd/Usage/stmdusage.html), and [Statamarkdown](https://ssc.wisc.edu/~hemken/Stataworkshops/Statamarkdown/stata-and-r-markdown.html)) Using `nbstata` with [Quarto](https://www.statalist.org/forums/forum/general-stata-discussion/general/1703835-ado-files-and-literate-programming) instead gives you a similar workflow, with greater flexibility of output."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The video below demonstrates using Stata in a Jupyter notebook. In addition to the [NBClassic](https://nbclassic.readthedocs.io/en/stable/notebook.html) application shown there, `nbstata` can also be used with [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html), [VS Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks), or [Quarto](https://quarto.org/).\n",
+    "\n",
+    "<img align=\"center\" width=\"650\" src=\"https://kylebarron.dev/stata_kernel/img/jupyter_notebook_example.gif\" alt=\"Animated demo showing major Stata kernel features in a Jupyter notebook\">"
    ]
   },
   {