Converts Jupyter Notebooks to Atlassian Confluence (R) pages using nbconvert
nbconflux is useful when:
- You use Jupyter notebooks to author computational narratives
- Your organization uses Confluence to store institutional knowledge
- You want an easy way to publish your work in that knowledge base
- Converts most cell inputs and outputs to valid Confluence storage format
- Attaches image outputs (e.g., matplotlib PNGs) to a page, shows them inline, and maintains the page-image association in the version history
- Attaches the source notebook to a page, links to it from the page footer, and maintains the page-notebook association in the version history
- Supports sweep-select Confluence comments over most input and output content
- Excludes input, output, or entire cells based on notebook cell tags
- Labels pages with
nbconfluxto identify content that originated as notebooks
- Inserts a table of contents macro at the top of the page based on notebook headings
- Applies the NBViewer stylesheet to pages to blend Confluence styling with Jupyter notebook styling (requires the CSS macro)
- Enables MathJax rendering (requires the HTML macro)
- Supports raw-cell passthrough of Confluence storage format markup (e.g., to include Confluence macros)
- Compatible with Confluence Cloud and Confluence Server
The nbconflux library requires Python 3 to run and
pip to install.
Once you've satisfied these prerequisites, run:
pip install nbconflux
(A conda package is coming soon.)
- Create or visit a page on your Confluence site.
- Copy the URL for the page.
- Run one of the following:
- In a shell:
nbconflux /path/to/a.ipynb https://your/page/url
- In a Python script, Jupyter Notebook, etc.:
import nbconflux html, resources = nbconflux.notebook_to_page(nb_path, url)
- In a shell:
- Enter your Confluence username and password when prompted.
- Visit the page to see your updates.
If you receive an error, see the project issues for known limitations on what you can post.
nbconflux -h at the command line for additional options and help.
usage: nbconflux [-h] [--exclude-toc] [--exclude-ipynb] [--exclude-style] [--include-mathjax] notebook url Converts Jupyter Notebooks to Atlassian Confluence pages using nbconvert positional arguments: notebook Path to local notebook (ipynb) url URL of Confluence page to update optional arguments: -h, --help show this help message and exit --exclude-toc Do not generate a table of contents --exclude-ipynb Do not attach the notebook to the page --exclude-style Do not include the Jupyter base stylesheet --include-mathjax Enable MathJax on the page --extra-labels EXTRA_LABELS [EXTRA_LABELS ...] Additional labels to add to the page Collects credentials from the following locations: 1. CONFLUENCE_USERNAME and CONFLUENCE_PASSWORD environment variables 2. ~/.nbconflux file in the format username:password 3. User prompts
We welcome issues and pull requests that help improve the variety of notebook content and Confluence installations nbconflux supports, its usability for humans, and its reusability within other tools.
We recommend creating a Python development environment using
make dev-env to install the runtime and development
requirements, and running
make test to execute the unit test suite on your
Q: Why not call it nbconfluence?
Q: Why do I have to create a page on the site first?
A: To avoid introducing the complexity of specifying a space, parent page, and title into the package.
Copyright (c) 2018 Valassis Digital under the terms of the BSD 3-Clause license
To run the tests:
make dev-env make test
To make a release:
- Meet all the requirements described in https://dustingram.com/articles/2018/03/16/markdown-descriptions-on-pypi to support pushing the Markdown README as the long description on PyPI.
git commit -m 'REL: 0.6.0' --allow-empty
git tag -a 0.6.0 -m 'REL: 0.6.0'
git push origin masterand
git push origin master --tagsor use a PR
- Enter your PyPI creds when prompted.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.