jupdoc 0.0.3

A package to convert Jupyter Notebooks to Word Documents (and other quarto supported formats) and upload them to Google Drive, with support for multiple user roles, using Quarto.

JupDoc: Streamlining Conversion of Jupyter Notebooks to Qurato Suppored Formats with multiple User-Levels 🚀

JupDoc is a Python package that simplifies the process of converting Jupyter Notebooks into multiple docx files (or other Quarto supported formats) while applying role-based access control based on cell tags.

Table of Contents

• About
• Features
• Installation
• Usage
• To Do
• License
• Acknowledgements
• Contributing

Please note that this package is still under development, and the documentation is not complete. There may be bugs and the API may change.

About

JupDoc is a Python package that simplifies the process of converting Jupyter Notebooks into multiple docx files or other formats while applying role-based access control based on cell tags. It is based on Quarto. The package is designed to be used in a JupyterHub environment where multiple users can access the same notebook. The package allows the user to define access roles using cell tags. The package then generates separate documents for each access role. The package can be used as a command line tool or as a python API.

The current version of the package supports the following formats:

• .ipynb (Jupyter Notebook) to .docx (Microsoft Word Document)
• .ipynb (Jupyter Notebook) to .pdf (Portable Document Format)
• .ipynb (Jupyter Notebook) to .html (Hypertext Markup Language)
• .ipynb (Jupyter Notebook) to .tex (LaTeX Document)
• .ipynb (Jupyter Notebook) to .md (Markdown Document)

The package also supports uploading the generated files to Google Drive. The package can be used with a Google Drive Service Account. The package can also be used without uploading the files to Google Drive.

Features

• Convert Jupyter Notebooks to docx, PDF, HTML, and more.
• Define access roles using cell tags.
• Generate separate documents for each access role.

Installation

You can install JupDoc using pip:

pip install jupdoc

JupDoc is based on Quarto to convert ipynb files to other formats. The instructions to install quarto can be found here.

Usage

We support two ways to convert notebooks to docs. The first one is using the command line interface. The second one is using the python API.

Note:

1. The conversion of .ipynb is based on Quarto and custom rending can be done by adding yaml config specific to notebooks as raw cells.
2. All cells in the notebook should have tags (including markdown cells), and the tags should be a part of the config used to export.

Command Line Interface

The command line interface can be used as follows:

jupdoc --config <config_file>

In case of absence of the config file, the configs can be passed as command line arguments:

jupdoc --filename <filename> --tags <tags> --prefix <prefix> --output <output> --format <format> --upload <upload> --folder_url <folder_url> --creds_path <creds_path>

The arguments are as follows:

• filename: The path to the notebook file.
• tags: The tags to be used for access control. Multiple tags can be passed as a comma-separated string.
• prefix: The prefix to be used for the output files.
• output: The path to the output directory.
• format: File format to be exported to.
• upload: Upload the files to Google Drive.
• folder_url: The URL of the Google Drive folder to upload the files to.
• creds_path: The path to the Google Drive credentials file. (For Service Account)

Python API

The python API can be used as follows:

from jupdoc import convert
args = {
    "filename": "notebook.ipynb",
    "tags": ["tag1", "tag2"],
    "prefix": "prefix",
    "output": "output",
    "format": "docx",
    "upload": True,
    "folder_url": "https://drive.google.com/drive/folders/1Qlw7SxdPr4Ag1mKl4-cTrjgJPgZyzzYb?usp=drive_link",
    "creds_path": "creds.json"
}
convert(**args)

To Do

1. Improve documentation. On-Going
2. Add support for report templates.
3. Add support for multiple cell tags.

License

This project is licensed under the terms of the MIT license.

Acknowledgements

This project is based on Quarto.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways:

• Report bugs.
• Fix bugs and submit pull requests.
• Write, clarify, or fix documentation.
• Suggest or add new features.

---