nbconflux

nbconflux使用nbconvert将Jupyter Notebooks转换为Atlassian Confluence页面。

为什么使用nbconflux？

当以下情况发生时，nbconflux非常有用：

• 您使用Jupyter notebooks来编写计算叙事
• 您的组织使用Confluence来存储机构知识
• 您希望以简单的方式将作品发布到知识库中

功能

• 将大多数单元输入和输出转换为有效的Confluence存储格式
• 将图像输出（例如，matplotlib PNGs）附加到页面，并显示为内联内容，同时维护版本历史中的页面-图像关联
• 将源笔记本附加到页面，并在页面页脚中链接到它，同时维护版本历史中的页面-笔记本关联
• 支持在大多数输入和输出内容上使用sweep-select Confluence评论
• 根据笔记本单元标签（code>noinput、nooutput或nocell）排除输入、输出或整个单元
• 使用nbconflux标签页面以标识源自笔记本的内容
• 根据笔记本标题在页面顶部插入目录宏
• 将NBViewer样式表应用于页面，以融合Confluence样式与Jupyter笔记本样式（需要CSS宏）
• 启用MathJax渲染（需要HTML宏）
• 支持Confluence存储格式标记的原始单元passthrough（例如，以包括Confluence宏）
• 与Confluence Cloud和Confluence Server兼容

安装

nbconflux库需要Python 3来运行，并使用pip来安装。一旦满足这些先决条件，运行

pip install nbconflux

（即将推出conda包。）

使用方法

1. 在您的Confluence网站上创建或访问一个页面。
2. 复制页面的URL。
3. 运行以下命令之一
   • 在shell中

     nbconflux /path/to/a.ipynb https://your/page/url
     

   • 在Python脚本、Jupyter Notebook等中

     import nbconflux
     html, resources = nbconflux.notebook_to_page(nb_path, url)
     

4. 根据提示输入您的Confluence用户名和密码。
5. 访问页面以查看您的更新。

如果您收到错误，请查看项目问题，以了解您可以发布的内容的限制。

在命令行中运行nbconflux -h以获取更多选项和帮助。

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

贡献

我们欢迎提交问题和拉取请求，以帮助改进nbconflux支持的笔记本内容多样性、Confluence安装的可使用性和在其他工具中的可重用性。

我们建议使用conda或virtualenv创建Python开发环境，运行make dev-env来安装运行时和开发需求，并运行make test在本地机器上执行单元测试套件。

常见问题解答

Q：为什么不叫nbconfluence？

A：https://atlassian.com/legal/trademark

Q：为什么我必须先在网站上创建一个页面？

A：为了避免将指定空间、父页面和标题的复杂性引入包中。

许可证

版权（c）2018 Valassis Digital，根据BSD 3-Clause许可证条款

开发

要运行测试

make dev-env
make test

维护

要发布版本

1. 满足https://dustingram.com/articles/2018/03/16/markdown-descriptions-on-pypi中描述的所有要求，以支持将Markdown README作为PyPI上的长描述推送。
2. git commit -m 'REL: 0.6.0' --allow-empty
3. git tag -a 0.6.0 -m 'REL: 0.6.0'
4. git push origin master和git push origin master --tags或使用PR
5. 运行make release。
6. 根据提示输入您的PyPI凭据。