Merge pull request #156 from nmfs-opensci/eeholmes-patch-1

add jupyterlab-quarto

book/_quarto.yml

@@ -21,7 +21,7 @@ book:
     - configuration_files.qmd
     - r-packages.qmd
     - desktop.qmd
-    - tex.qmd
+    - publishing.qmd
     - jupyter-config.qmd
     - developers.qmd
 

book/configuration_files.qmd

@@ -6,6 +6,7 @@ The helper scripts at `/pyrocket_scripts` in the image scripts to help do common
 * `install-pip-packages.sh`
 * `install-r-packages.sh`
 * `install-apt-packages.sh`
+* `install-vscode-extensions.sh`
 * `install-desktop.sh`
 * `setup-start.sh`
 * `run-postbuild.sh`
@@ -147,6 +148,24 @@ RUN /pyrocket_scripts/setup-start.sh start
 RUN rm start
 ```
 
+## install-vscode-extensions.sh
+
+The `install-vscode-extensions.sh` script will add VSCode extensions.
+
+```
+COPY vscode-extensions.txt vscode-extensions.txt
+RUN /pyrocket_scripts/install-vscode-extensions.sh vscode-extensions.txt
+RUN rm vscode-extensions.txt
+```
+
+vscode-extensions.txt
+```
+gitlens
+indent-rainbow
+code-spell-checker
+prettier
+```
+
 ## Desktop applications
 
 See the [chapter on Desktop applications](desktop.html). 

book/customizing.qmd

@@ -12,6 +12,7 @@ How to use the helper scripts is shown in [configuration files](configuration_fi
 * `install-pip-packages.sh`
 * `install-r-packages.sh`
 * `install-apt-packages.sh`
+* `install-vscode-extensions.sh`
 * `install-desktop.sh`
 * `setup-start.sh`
 * `run-postbuild.sh`

book/publishing.qmd

@@ -0,0 +1,90 @@
+# Publishing
+
+py-rocket-base has a number of packages to help with creation of documentation, books and webpages from content: Sphinx, Quarto, and Myst. Pandoc is installed which allows output to many different formats including html, Word, markdown and PDF. TexLive (for PDF output) is installed with tlmgr to handle package installation.
+
+## Quarto
+
+![](assets/quarto-illustration.png)
+
+Quarto is a full-feature platform for creation of documents, books and webpages in a variety of formats. Explore the documentation at [https://quarto.org/](https://quarto.org/). You can use Quarto in JupyterLab, RStudio or VSCode. RStudio has the most featured integration followed by VSCode. JupyterLab integration is somewhat minimal.
+
+### RStudio
+
+Quarto is fully integrated with RStudio. Use the Render and Build buttons.
+
+**Special note regarding creating pdfs**
+
+Rendering to PDF or `format: pdf` should work fine and packages will be installed on the fly. But the package installations will not persist and you will need to install them again after you restart the server.
+
+### VSCode
+
+The VSCode Quarto extension is installed. This provides many nice features. Read about them on the Quarto [VSCode](https://quarto.org/docs/tools/vscode.html) page. The extension includes keyboard shortcuts for rendering or you can render from a terminal.
+
+### Jupyter Lab
+
+The `jupyterlab-quarto` package is installed which allows Quarto markdown to be rendered in markdown cells in Jupyter notebooks (ipynb). But you will need to render from a terminal. Quarto render both `qmd` and `ipynb` files. Read about using Quarto with JupyterLab on this Quarto [page](https://quarto.org/docs/tools/jupyter-lab.html). For example,
+
+```
+quarto render --to pdf test.qmd
+quarto render --to html test.ipynb
+```
+
+For PDF output, TexLive packages will not install on the fly and you will need to do `tlmgr install packagename` for any missing package errors you get.
+
+## MyST
+
+<div>
+<div style="float: right; position: relative; top: 0px; padding: 2px;">
+![](assets/myst.svg){width=200px}
+</div>
+
+[MyST](https://mystmd.org/) is an Python ecosystem of tools for creating interactive scientific publications for the web or export to PDF, LaTeX and Microsoft Word. [jupyterlab-myst](https://jupyter-book.github.io/jupyterlab-myst/) extension is installed. Read more about MyST in JupyterLab [here](https://mystmd.org/guide/quickstart-jupyter-lab-myst). The [MyST VSCode extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) is also installed if you are editting MyST markdown in VSCode.
+</div>
+
+**Creating PDFs with Myst**
+
+You can output to PDF like so from a terminal: `jupyter nbconvert --to pdf test.ipynb`.
+However. TexLive packages will not install on the fly and you will need to do `tlmgr install packagename` for any missing package errors you get.
+
+## Sphinx
+
+<div>
+<div style="float: right; position: relative; top: 0px; padding: 2px;">
+![](assets/sphinx.png){width=200px}
+</div>
+
+[Sphinx](https://www.sphinx-doc.org/en/master/) is a commonly used package for creating documentation for Python packages.
+</div>
+
+## TexLive
+
+<div>
+<div style="float: right; position: relative; top: 0px; padding: 2px;">
+![](assets/texlive.png)
+</div>
+
+py-rocket-base has Quarto and Myst installed along with pandoc and TeXLive for output to PDF. The tlmgr is used (and must be used) to manage packages. 
+
+</div>
+
+
+### Installing new TexLive packages
+
+tlmgr must be used.
+
+* Do not use `apt-get` to install texlive packages. This will turn off tlmgr (the TeX package manager). Instead use
+```
+tlmgr install <package>
+```
+* Run `tlmgr option` to make sure tlmgr is working.
+
+Unfortunately any packages you install will be in the `/opt` directory and this gets recreated every time you restart your server. So if you need a
+particular package you will need to keep installing it. Or create your own image based on py-rocket-base:
+
+Dockerfile
+```
+FROM ghcr.io/nmfs-opensci/py-rocket-base:latest
+
+RUN tlmgr install collection-latexrecommended && tlmgr clean --all
+```
+

docs/configuration_files.html

@@ -148,8 +148,8 @@
 </li>
         <li class="sidebar-item">
   <div class="sidebar-item-container"> 
-  <a href="./tex.html" class="sidebar-item-text sidebar-link">
- <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Creating PDFs</span></span></a>
+  <a href="./publishing.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Publishing</span></span></a>
   </div>
 </li>
         <li class="sidebar-item">
@@ -183,7 +183,8 @@ <h2 id="toc-title">Table of contents</h2>
   <li><a href="#install-apt-packages.sh" id="toc-install-apt-packages.sh" class="nav-link" data-scroll-target="#install-apt-packages.sh"><span class="header-section-number">2.4</span> install-apt-packages.sh</a></li>
   <li><a href="#run-postbuild.sh" id="toc-run-postbuild.sh" class="nav-link" data-scroll-target="#run-postbuild.sh"><span class="header-section-number">2.5</span> run-postbuild.sh</a></li>
   <li><a href="#setup-start.sh" id="toc-setup-start.sh" class="nav-link" data-scroll-target="#setup-start.sh"><span class="header-section-number">2.6</span> setup-start.sh</a></li>
-  <li><a href="#desktop-applications" id="toc-desktop-applications" class="nav-link" data-scroll-target="#desktop-applications"><span class="header-section-number">2.7</span> Desktop applications</a></li>
+  <li><a href="#install-vscode-extensions.sh" id="toc-install-vscode-extensions.sh" class="nav-link" data-scroll-target="#install-vscode-extensions.sh"><span class="header-section-number">2.7</span> install-vscode-extensions.sh</a></li>
+  <li><a href="#desktop-applications" id="toc-desktop-applications" class="nav-link" data-scroll-target="#desktop-applications"><span class="header-section-number">2.8</span> Desktop applications</a></li>
   </ul>
 <div class="toc-actions"><ul><li><a href="https://github.com/nmfs-opensci/py-rocket-base/edit/main/configuration_files.qmd" class="toc-action"><i class="bi bi-github"></i>Edit this page</a></li><li><a href="https://github.com/nmfs-opensci/py-rocket-base/blob/main/configuration_files.qmd" class="toc-action"><i class="bi empty"></i>View source</a></li><li><a href="https://github.com/nmfs-opensci/py-rocket-base/issues/new" class="toc-action"><i class="bi empty"></i>Report an issue</a></li></ul></div></nav>
     </div>
@@ -215,6 +216,7 @@ <h1 class="title"><span class="chapter-number">2</span>&nbsp; <span class="chapt
 <li><code>install-pip-packages.sh</code></li>
 <li><code>install-r-packages.sh</code></li>
 <li><code>install-apt-packages.sh</code></li>
+<li><code>install-vscode-extensions.sh</code></li>
 <li><code>install-desktop.sh</code></li>
 <li><code>setup-start.sh</code></li>
 <li><code>run-postbuild.sh</code></li>
@@ -311,8 +313,20 @@ <h2 data-number="2.6" class="anchored" data-anchor-id="setup-start.sh"><span cla
 RUN /pyrocket_scripts/setup-start.sh start
 RUN rm start</code></pre>
 </section>
-<section id="desktop-applications" class="level2" data-number="2.7">
-<h2 data-number="2.7" class="anchored" data-anchor-id="desktop-applications"><span class="header-section-number">2.7</span> Desktop applications</h2>
+<section id="install-vscode-extensions.sh" class="level2" data-number="2.7">
+<h2 data-number="2.7" class="anchored" data-anchor-id="install-vscode-extensions.sh"><span class="header-section-number">2.7</span> install-vscode-extensions.sh</h2>
+<p>The <code>install-vscode-extensions.sh</code> script will add VSCode extensions.</p>
+<pre><code>COPY vscode-extensions.txt vscode-extensions.txt
+RUN /pyrocket_scripts/install-vscode-extensions.sh vscode-extensions.txt
+RUN rm vscode-extensions.txt</code></pre>
+<p>vscode-extensions.txt</p>
+<pre><code>gitlens
+indent-rainbow
+code-spell-checker
+prettier</code></pre>
+</section>
+<section id="desktop-applications" class="level2" data-number="2.8">
+<h2 data-number="2.8" class="anchored" data-anchor-id="desktop-applications"><span class="header-section-number">2.8</span> Desktop applications</h2>
 <p>See the <a href="desktop.html">chapter on Desktop applications</a>.</p>
 
 

docs/customizing.html

@@ -148,8 +148,8 @@
 </li>
         <li class="sidebar-item">
   <div class="sidebar-item-container"> 
-  <a href="./tex.html" class="sidebar-item-text sidebar-link">
- <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Creating PDFs</span></span></a>
+  <a href="./publishing.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Publishing</span></span></a>
   </div>
 </li>
         <li class="sidebar-item">
@@ -224,6 +224,7 @@ <h3 data-number="1.1.1" class="anchored" data-anchor-id="pyrocket-scripts"><span
 <li><code>install-pip-packages.sh</code></li>
 <li><code>install-r-packages.sh</code></li>
 <li><code>install-apt-packages.sh</code></li>
+<li><code>install-vscode-extensions.sh</code></li>
 <li><code>install-desktop.sh</code></li>
 <li><code>setup-start.sh</code></li>
 <li><code>run-postbuild.sh</code></li>

docs/desktop.html

@@ -29,7 +29,7 @@
 <script src="site_libs/quarto-search/fuse.min.js"></script>
 <script src="site_libs/quarto-search/quarto-search.js"></script>
 <meta name="quarto:offset" content="./">
-<link href="./tex.html" rel="next">
+<link href="./publishing.html" rel="next">
 <link href="./r-packages.html" rel="prev">
 <link href="./assets/favicon.ico" rel="icon">
 <script src="site_libs/quarto-html/quarto.js"></script>
@@ -148,8 +148,8 @@
 </li>
         <li class="sidebar-item">
   <div class="sidebar-item-container"> 
-  <a href="./tex.html" class="sidebar-item-text sidebar-link">
- <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Creating PDFs</span></span></a>
+  <a href="./publishing.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Publishing</span></span></a>
   </div>
 </li>
         <li class="sidebar-item">
@@ -897,8 +897,8 @@ <h2 data-number="4.2" class="anchored" data-anchor-id="whats-happening"><span cl
       </a>          
   </div>
   <div class="nav-page nav-page-next">
-      <a href="./tex.html" class="pagination-link" aria-label="Creating PDFs">
-        <span class="nav-page-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Creating PDFs</span></span> <i class="bi bi-arrow-right-short"></i>
+      <a href="./publishing.html" class="pagination-link" aria-label="Publishing">
+        <span class="nav-page-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Publishing</span></span> <i class="bi bi-arrow-right-short"></i>
       </a>
   </div>
 </nav>

docs/developers.html

@@ -181,8 +181,8 @@
 </li>
         <li class="sidebar-item">
   <div class="sidebar-item-container"> 
-  <a href="./tex.html" class="sidebar-item-text sidebar-link">
- <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Creating PDFs</span></span></a>
+  <a href="./publishing.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text"><span class="chapter-number">5</span>&nbsp; <span class="chapter-title">Publishing</span></span></a>
   </div>
 </li>
         <li class="sidebar-item">