From a184c8329db1c6aa83e05c1d14d121e4a48191ae Mon Sep 17 00:00:00 2001 From: Tim Huegerich Date: Tue, 5 Nov 2024 13:52:37 -0600 Subject: [PATCH] Remove code styling of "nbstata" --- README.md | 40 ++++++++++++++++++++-------------------- nbs/01_config.ipynb | 2 +- nbs/dev_docs_index.qmd | 2 +- nbs/index.ipynb | 30 +++++++++++++++--------------- nbs/user_guide.ipynb | 28 ++++++++++++++-------------- 5 files changed, 51 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index cf63997..1c8b8a0 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@   -`nbstata` is a [Jupyter +*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). @@ -23,12 +23,12 @@ 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. -`nbstata` allows you to create Stata notebooks (as opposed to [using +*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). -### Key nbstata features +### Key *nbstata* features - [x] [Easy setup](https://hugetim.github.io/nbstata/user_guide.html#install) @@ -46,6 +46,17 @@ which is needlessly clunky if you are working primarily with Stata). - [x] Quarto [inline code](https://quarto.org/docs/computations/inline-code.html) support +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 GIF demoing major Stata kernel features + ### What can you do with Stata notebooks… …that you can’t do with the [official Stata @@ -64,20 +75,9 @@ interface](https://www.stata.com/features/overview/graphical-user-interface/)? 4. [links](https://hugetim.github.io/nbstata/) 5. math: $y_{it}=\beta_0+\varepsilon_{it}$ -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 GIF demoing major Stata kernel features - ## Contributing -`nbstata` is being developed using +*nbstata* is being developed using [nbdev](https://nbdev.fast.ai/blog/posts/2022-07-28-nbdev2/#whats-nbdev). The `/nbs` directory is where edits to the source code should be made. (The python code is then exported to the `/nbdev` library folder.) @@ -87,12 +87,12 @@ For more, see ## Acknowledgements -Kyle Barron authored the original `stata_kernel`, which works for older +Kyle Barron authored the original *stata_kernel*, which works for older versions of Stata. Vinci Chow created a Stata kernel that instead uses [pystata](https://www.stata.com/python/pystata18/), which first became -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`. +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) @@ -101,7 +101,7 @@ of the docs and newer features are derived from `stata_kernel`. [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 + 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/01_config.ipynb b/nbs/01_config.ipynb index 3df6c51..b6df4fd 100644 --- a/nbs/01_config.ipynb +++ b/nbs/01_config.ipynb @@ -1003,7 +1003,7 @@ "id": "88a18fec", "metadata": {}, "source": [ - "If the configuration file has invalid width/height, the error message says \"Graph size not changed\" even though, under the hood, the `pystata` graph size configuration is changing from \"default\" to definite measures. This behavior ensures that using the %set magic to change just one of the size values, width or height, always exhibits the behavior described in the `nbstata` [user guide](https://hugetim.github.io/nbstata/user_guide.html#configuration-optional) rather than the (maintained aspect ratio) [behavior described in the pystata docs](https://www.stata.com/python/pystata18/config.html#pystata.config.set_graph_size). " + "If the configuration file has invalid width/height, the error message says \"Graph size not changed\" even though, under the hood, the *pystata* graph size configuration is changing from \"default\" to definite measures. This behavior ensures that using the %set magic to change just one of the size values, width or height, always exhibits the behavior described in the *nbstata* [user guide](https://hugetim.github.io/nbstata/user_guide.html#configuration-optional) rather than the (maintained aspect ratio) [behavior described in the pystata docs](https://www.stata.com/python/pystata18/config.html#pystata.config.set_graph_size). " ] }, { diff --git a/nbs/dev_docs_index.qmd b/nbs/dev_docs_index.qmd index 0caa92a..5abb6a8 100644 --- a/nbs/dev_docs_index.qmd +++ b/nbs/dev_docs_index.qmd @@ -23,7 +23,7 @@ listing: - 14_kernel.ipynb - 15_install.ipynb --- -For information on how to help improve the `nbstata` code, see: [CONTRIBUTING.md](https://github.com/hugetim/nbstata/blob/master/CONTRIBUTING.md) +For information on how to help improve the *nbstata* code, see: [CONTRIBUTING.md](https://github.com/hugetim/nbstata/blob/master/CONTRIBUTING.md) The main dependencies among the principal nbstata modules: ```{mermaid} diff --git a/nbs/index.ipynb b/nbs/index.ipynb index 6bb4a99..4782a61 100644 --- a/nbs/index.ipynb +++ b/nbs/index.ipynb @@ -15,7 +15,7 @@ "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)." + "*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)." ] }, { @@ -40,14 +40,14 @@ "source": [ "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)." + "*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": [ - "### Key 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", @@ -60,6 +60,15 @@ "- [x] Quarto [inline code](https://quarto.org/docs/computations/inline-code.html) support" ] }, + { + "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" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -86,16 +95,7 @@ " 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." - ] - }, - { - "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" + "[^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." ] }, { @@ -109,7 +109,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`nbstata` is being developed using [nbdev](https://nbdev.fast.ai/blog/posts/2022-07-28-nbdev2/#whats-nbdev). The `/nbs` directory is where edits to the source code should be made. (The python code is then exported to the `/nbdev` library folder.)\n", + "*nbstata* is being developed using [nbdev](https://nbdev.fast.ai/blog/posts/2022-07-28-nbdev2/#whats-nbdev). The `/nbs` directory is where edits to the source code should be made. (The python code is then exported to the `/nbdev` library folder.)\n", "\n", "For more, see [CONTRIBUTING.md](https://github.com/hugetim/nbstata/blob/master/CONTRIBUTING.md)." ] @@ -125,7 +125,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Kyle Barron authored the original `stata_kernel`, which works for older versions of Stata. Vinci Chow created a Stata kernel that instead uses [pystata](https://www.stata.com/python/pystata18/), which first became 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`." + "Kyle Barron authored the original *stata_kernel*, which works for older versions of Stata. Vinci Chow created a Stata kernel that instead uses [pystata](https://www.stata.com/python/pystata18/), which first became 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*." ] } ], diff --git a/nbs/user_guide.ipynb b/nbs/user_guide.ipynb index a4c2d19..0cb5e03 100644 --- a/nbs/user_guide.ipynb +++ b/nbs/user_guide.ipynb @@ -6,7 +6,7 @@ "source": [ "# User Guide\n", "\n", - "> Instructions for using `nbstata` as a Jupyter kernel" + "> Instructions for using nbstata as a Jupyter kernel" ] }, { @@ -15,7 +15,7 @@ "source": [ "## Getting Started\n", "\n", - "It doesn't take much to get `nbstata` up and running. Here's how:" + "It doesn't take much to get *nbstata* up and running. Here's how:" ] }, { @@ -25,12 +25,12 @@ "### Prerequisites\n", "\n", "#### Stata\n", - "Because `nbstata` uses [pystata](https://www.stata.com/python/pystata18/) under the hood, a currently-licensed version of Stata 17+ must already be installed. *(If you have an older version of Stata, consider [stata_kernel](https://github.com/kylebarron/stata_kernel) instead.)*\n", + "Because *nbstata* uses [pystata](https://www.stata.com/python/pystata18/) under the hood, a currently-licensed version of Stata 17+ must already be installed. *(If you have an older version of Stata, consider [stata_kernel](https://github.com/kylebarron/stata_kernel) instead.)*\n", "\n", "::: {.callout-note collapse=\"true\"}\n", "## Stata troubleshooting (particularly for Arch Linux) \n", "\n", - "Make sure that the `stata` command (that is, the CLI to Stata, not to be confused with `xstata`, which is the GUI) works, otherwise `nbstata` won't work.\n", + "Make sure that the `stata` command (that is, the CLI to Stata, not to be confused with `xstata`, which is the GUI) works, otherwise *nbstata* won't work.\n", "\n", "In particular, if you are on Arch Linux and you get this error when running `stata`:\n", "```\n", @@ -47,7 +47,7 @@ " administrator privileges and is the simplest way to install Python, JupyterLab and many of the most popular scientific packages.\n", "\n", "(However, the full Anaconda installation is quite large, and it includes many libraries for Python that\n", - " `nbstata` doesn't use. If you don't plan to use Python and want to use\n", + " *nbstata* doesn't use. If you don't plan to use Python and want to use\n", " less disk space, install [Miniconda](https://conda.io/miniconda.html), a bare-bones version of Anaconda. \n", " Then, at an Anaconda prompt, type `conda install jupyterlab` to install JupyterLab.)\n", " \n", @@ -58,7 +58,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Install `nbstata`\n", + "### Install *nbstata*\n", "\n", "To download and install the python package run the following at an Anaconda prompt:\n", "```sh\n", @@ -89,7 +89,7 @@ "\n", "#### Updating\n", "\n", - "To upgrade from a previous version of `nbstata`, run:\n", + "To upgrade from a previous version of *nbstata*, run:\n", "\n", "```sh\n", "pip install nbstata --upgrade\n", @@ -151,8 +151,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Both `pystata` and `stata_kernel` default to the SVG image format. \n", - "`nbstata` defaults to the PNG image format instead for several reasons:\n", + "Both *pystata* and *stata_kernel* default to the SVG image format. \n", + "*nbstata* (like *pystata-kernel*) defaults to the PNG image format instead for several reasons:\n", "\n", "- Jupyter does not show SVG images from untrusted notebooks ([link 1](https://stackoverflow.com/questions/68398033/svg-figures-hidden-in-jupyterlab-after-some-time)).\n", "- Notebooks with empty cells are untrusted ([link 2](https://github.com/jupyterlab/jupyterlab/issues/9765)).\n", @@ -204,11 +204,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "'Magics' are commands provided by `nbstata` that enhance the experience of working with Stata in Jupyter. They work only when placed at the beginning of a code cell. \n", + "'Magics' are commands provided by *nbstata* that enhance the experience of working with Stata in Jupyter. They work only when placed at the beginning of a code cell. \n", "\n", - "Jupyter magics typically start with `%`, but `nbstata` magics may alternatively be prefixed with `*%` so that, if you export a Stata notebook to a .do file and run it that way, the magics will not cause errors.\n", + "Jupyter magics typically start with `%`, but *nbstata* magics may alternatively be prefixed with `*%` so that, if you export a Stata notebook to a .do file and run it that way, the magics will not cause errors.\n", "\n", - "`nbstata` currently supports the following magics:\n", + "*nbstata* currently supports the following magics:\n", "\n", "| Magic | Description | Full Syntax |\n", "| :-- | :-- | :-- |\n", @@ -442,7 +442,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The default `echo = None` configuration does some complicated things under the hood to emulate functionality that `pystata` does not directly support: running multi-line Stata code without echoing the commands. While extensive automatic tests are in place to help ensure its reliability, unanticipated issues may arise. If, while using this mode, a particular code cell is not working as expected, try placing the `%%echo` magic at the top of it to see if that resolves the issue. (If so, please report that [here](https://github.com/hugetim/nbstata/issues/new?labels=bug).) You can also avoid such potential issues by setting the config `echo = False`, which will at least not echo single-line Stata commands though it will echo multiple commands." + "The default `echo = None` configuration does some complicated things under the hood to emulate functionality that *pystata* does not directly support: running multi-line Stata code without echoing the commands. While extensive automatic tests are in place to help ensure its reliability, unanticipated issues may arise. If, while using this mode, a particular code cell is not working as expected, try placing the `%%echo` magic at the top of it to see if that resolves the issue. (If so, please report that [here](https://github.com/hugetim/nbstata/issues/new?labels=bug).) You can also avoid such potential issues by setting the config `echo = False`, which will at least not echo single-line Stata commands though it will echo multiple commands." ] }, { @@ -487,7 +487,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "`nbstata` can be used with [Quarto](https://quarto.org/), starting from either a notebook or a .qmd markdown file, to create output in a wide variety of formats. Just include `jupyter: nbstata` in the document-level YAML at the top and use `*|` as the prefix for cell options.\n", + "*nbstata* can be used with [Quarto](https://quarto.org/), starting from either a notebook or a .qmd markdown file, to create output in a wide variety of formats. Just include `jupyter: nbstata` in the document-level YAML at the top and use `*|` as the prefix for cell options.\n", "\n", "### Inline calculations\n", "\n",