fastai / fastdoc Goto Github PK

View Code? Open in Web Editor NEW

226.0 7.0 28.0 1.54 MB

Create publication-quality books from Jupyter notebooks

Home Page: https://fastai.github.io/fastdoc/

License: Apache License 2.0

Jupyter Notebook 96.94% Python 2.95% Makefile 0.06% Smarty 0.06%

book asciidoc nbdev jupyter notebook publish fastai

fastdoc's Introduction

fastdoc

Create publication-quality books from Jupyter notebooks

The output of fastdoc is an asciidoc file for each input notebook. You can then use asciidoctor to convert that to HTML, DocBook, epub, mobi, and so forth.

Install

To install using pip:

pip install fastdoc

To install using Conda:

conda install -c fastai fastdoc

How to use

Suppose your notebook is in a folder called book. To run fastdoc:

fastdoc_convert_all --path book --dest_path convert_book

You'll find your exported asciidoc files and all images used in convert_book.

For a single notebook demonstrating all the features of fastdoc, see the test/_test.ipynb notebook.

For a complete O'Reilly book written in this way, see fastbook.

fastdoc's People

Contributors

Stargazers

Watchers

fastdoc's Issues

Keep-Alive-Actions

Should some errors be warnings?

On my first pass through my notebooks, I am seeing two errors:

Found a non-processed block quote, please fix
Found code too long in a cell

Both are errors, so they cause the conversion to stop. Could these be warnings? I would like to convert these documents anyway, and clean up these issues later.

Unexpected new line in numbered list

The asciidoc conversion for numbered lists sometimes introduces a new line that causes the resulting HTML / PDF to be incorrectly formatted.

For example, the following markdown cell


1. one
1. two
1. three
1. four
1. five
1. six

produces the following asciidoc output

. one
. two
. three
. four
. five
.
six

The new line before six causes this item to be treated as part of the fifth one

Steps to reproduce

Download the sample notebook fastdoc_numbered_list.ipynb from this gist and place it in some folder, e.g. book
Run

fastdoc_convert_all --path path/to/book --dest_path output

Environment details

fastdoc 0.0.2
pandoc 2.3.1

Hyperlinks break when included in note, tip, and warning elements

Asciidoc markup expects hyperlinks to be formatted as follows:

Visit the http://oreilly.com[O'Reilly website]

fastdoc doesn't perform the appropriate conversion from Markdown to Asciidoc for the note, tip, and warning elements. For example, consider adding a hyperlink to the following Note element in a Jupyter notebook:

> Note: This is a note with some [link](https://github.com/fastai)

Expected Asciidoc

[NOTE]
====
This is a note with some https://github.com/fastai[link]
====

Actual Asciidoc

[NOTE]
====
This is a note with some [link](https://github.com/fastai)
====

Folder structure

First of all thanks for releasing the conversion scripts as a library! I followed the instructions in the Readme and created a folder in my repo called ./books/ and ran the fastdoc_convert_all within the folder but got the following error:

FileNotFoundError: [Errno 2] No such file or directory: 'book'

When running the fastdoc_convert_all one level up outside the book folder but inside the repo (./) it worked, however the convert_book was created one level higher outside the repo (../convert_books). Is this the intended behaviour? If not I can look into it and create a PR.

Put a reference target in a Markdown cell?

It looks like there are two ways to include a reference target in a notebook:

In a raw cell, you can put an asciidoc target [[like_this]]
In a code cell, you can add a comment #like_this

Is there any way to include a reference target in a Markdown cell?

Keep-Alive-Actions

Links in block quotes don't get translated

Here's an example from Think Bayes. The Markdown input is

If you were inclined to choose the second option, you are in good company.  The biologist [Stephen J. Gould wrote](https://sci-hub.tw/https://doi.org/10.1080/09332480.1989.10554932) :

> I am particularly fond of this example because I know that the [second] statement is least probable, yet a little [homunculus](https://en.wikipedia.org/wiki/Homunculus_argument) in my head continues to jump up and down, shouting at me, "but she can't just be a bank teller; read the description."

And the asciidoc output is

If you were inclined to choose the second option, you are in good
company. The biologist
https://sci-hub.tw/https://doi.org/10.1080/09332480.1989.10554932[Stephen
J. Gould wrote] :

____
I am particularly fond of this example because I know that the [second] statement is least probable, yet a little [homunculus](https://en.wikipedia.org/wiki/Homunculus_argument) in my head continues to jump up and down, shouting at me, "but she can't just be a bank teller; read the description."
____

So it looks like the first link has been translated and the second passed through.

How to change image resolution?

When fastdoc converts figures to png, the default resolution is too low for printing. Is there a way to either increase the resolution or generate pdf?

Correct footnote example in _test.ipynb?

Hi @jph00,

In the test notebook, the footnote example is shown as

A footnote[this is a footnote]

however my understanding from the AsciiDoc docs is that a colon is required to render the footnote, i.e.

A footnote:[this is a footnote]

If you agree, I'd be happy to fix the test notebook!

Keep-Alive-Actions

Text wrapping causes misinterpretation

In the source notebook I have the following bullet item:

* The host, Monty Hall, shows you three closed doors numbered 1, 2, and 3. He tells you that there is a prize behind each door.

After fastdoc converts to asciidoc, it looks like this:

* The host, Monty Hall, shows you three closed doors numbered 1, 2, and
3. He tells you that there is a prize behind each door.

Because the second line begins with 3. , it gets interpreted as a numbered list item.

Is text wrapping necessary? Can it be turned off?

Or should I edit the text so the line break falls in a different place :)

Thanks!

Keep-Alive-Actions

Debug Errors Not Converting Correctly

We've run into an issue where we're trying to include debug info, e.g.,

---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
<ipython-input-2-b2e110f6fc8f> in <module>()
----> 1 func2(1)

<ipython-input-1-d849e34d61fb> in func2(x)
      5     a = x
      6     b = x - 1
----> 7     return func1(a, b)

<ipython-input-1-d849e34d61fb> in func1(a, b)
      1 def func1(a, b):
----> 2     return a / b
      3 
      4 def func2(x):
      5     a = x

ZeroDivisionError: division by zero

in a book, but the command characters in the backend (e.g., \u001b[0m\n\u001b[0;31mZeroDivisionError...) are breaking the asciidoc conversion (and also throwing build errors, since the command characters are appearing in the adoc).

I'm basically looking for a "clean" step when converting code blocks -- any (preferably easy) way to do this?

initial public release

ImportError: cannot import name 'soft_unicode' from 'markupsafe'

It seems like an upstream dependency has changed such that a fresh pip install fastdoc no longer converts off the bat as expected:

% fastdoc_convert_all --path notebooks --dest_path asciidoc

Traceback (most recent call last):
  File "/Users/usr/.virtualenvs/pdsh2e/bin/fastdoc_convert_all", line 5, in <module>
    from fastdoc.asciidoc import fastdoc_convert_all
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/fastdoc/asciidoc.py", line 14, in <module>
    from .imports import *
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/fastdoc/imports.py", line 2, in <module>
    import os.path, re, nbformat, jupyter_contrib_nbextensions, glob, shutil
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/jupyter_contrib_nbextensions/__init__.py", line 5, in <module>
    import jupyter_nbextensions_configurator
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/jupyter_nbextensions_configurator/__init__.py", line 18, in <module>
    from notebook.base.handlers import APIHandler, IPythonHandler
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/notebook/base/handlers.py", line 21, in <module>
    from jinja2 import TemplateNotFound
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/jinja2/__init__.py", line 12, in <module>
    from .environment import Environment
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/jinja2/environment.py", line 25, in <module>
    from .defaults import BLOCK_END_STRING
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/jinja2/defaults.py", line 3, in <module>
    from .filters import FILTERS as DEFAULT_FILTERS  # noqa: F401
  File "/Users/usr/.virtualenvs/pdsh2e/lib/python3.10/site-packages/jinja2/filters.py", line 13, in <module>
    from markupsafe import soft_unicode
ImportError: cannot import name 'soft_unicode' from 'markupsafe'

Fix seems to be to pin markupsafe to an older version (e.g., markupsafe==2.0.1), but it would probably be good to fix the import.

table conversion doesn't work

I have tested out converting fastbook into asciidoc and pdf using asciidoctor and asciidoctor-pdf.
everything looks nicely rendered except for table. it seems like table rendering shows raw HTML tags.

I attach an example screenshot. (from chapter 10)

Asciidoc conversion does not respect heading levels

Hi @jph00,

First of all, thank you for open-sourcing this tool - it's super useful for a textbook I'm currently working on!

I'm running into a small problem with the heading levels. Please see the details below.

Description of the problem

I have a notebook with different heading levels (simple gist here) all of which appear with the same == level in the resulting .asciidoc file.

Is this by design or does one need to add a special flag to the markdown cells?

Steps to reproduce

Download the simple notebook from this gist
Run the following commands

cd path/to/fastdoc_sections_test.ipynb
mkdir images
fastdoc_convert_all --path ./ --dest_path convert_book

Expected output

An fastdoc_sections_test.asciidoc file with the following content

== Heading level 1

=== Heading level 2

==== Heading level 3

Actual output

== Heading level 1

== Heading level 2

== Heading level 3

Keep-Alive-Actions

Problem with chapter and section headings

I'm having an odd problem with chapter and section headings. It's odd because it was previously working; I don't think I changed anything, and now it's not working.

Here's the minimum test case that replicates the problem. I have a notebook that looks like this:

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Chapter Title\n",
    "\n",
    "Some text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Section Title\n",
    "\n",
    "More text\n"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}

And then I run fastdoc like this

fastdoc_convert_all --path . --dest_path convert_book

And here's the output

== Chapter Title

Some text

== Section Title

More text

I was expecting the first one to be a chapter heading and the second to be a section heading.

And then I'm extra confused because when I build this on Atlas I get two chapters instead of two sections.

Any idea what's happening?

conda installation channel

Was wondering if it should really be
conda install fastdoc
or if it should be
conda install -c fastai fastdoc
as also here: https://anaconda.org/fastai/fastdoc

fastai / fastdoc Goto Github PK

fastdoc's Introduction

fastdoc

Install

How to use

fastdoc's People

Contributors

Stargazers

Watchers

Forkers

fastdoc's Issues

Steps to reproduce

Environment details

Expected Asciidoc

Actual Asciidoc

Description of the problem

Steps to reproduce

Expected output

Actual output

Recommend Projects

Recommend Topics

Recommend Org