5 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.
5.1 Quarto
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/. You can use Quarto in JupyterLab, RStudio or VSCode. RStudio has the most featured integration followed by VSCode. JupyterLab integration is somewhat minimal.
5.1.1 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.
5.1.2 VSCode
The VSCode Quarto extension is installed. This provides many nice features. Read about them on the Quarto VSCode page. The extension includes keyboard shortcuts for rendering or you can render from a terminal.
5.1.3 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. 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.
5.2 MyST
MyST is an Python ecosystem of tools for creating interactive scientific publications for the web or export to PDF, LaTeX and Microsoft Word. jupyterlab-myst extension is installed. Read more about MyST in JupyterLab here. The MyST VSCode extension is also installed if you are editting MyST markdown in VSCode.
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.
5.3 Sphinx
Sphinx is a commonly used package for creating documentation for Python packages.
5.4 TexLive
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.
5.4.1 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