From 25f187e25f15612a96e67233ebe046a18ad39c78 Mon Sep 17 00:00:00 2001 From: Tim Huegerich Date: Tue, 5 Nov 2024 13:02:59 -0600 Subject: [PATCH] Update README, incl. image alt text --- README.md | 62 +++++++++++++++++++++++++++++-------------------- nbs/custom.yml | 3 +++ nbs/index.ipynb | 42 +++++++++++++++++++++++---------- 3 files changed, 70 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 718f663..4976666 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ +  + `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). - - -### `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. + 3. 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/). + +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 index 66ee9df..d1b5591 100644 --- 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 index 056c02c..882d83c 100644 --- a/nbs/index.ipynb +++ b/nbs/index.ipynb @@ -13,6 +13,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ + " \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)." ] }, @@ -20,7 +22,9 @@ "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", + " " ] }, { @@ -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", - "" + "`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", + " " + ] + }, + { + "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. \n", + " 3. \"WordArt\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", + "\"Animated" ] }, {