fastai / fastdoc Goto Github PK
View Code? Open in Web Editor NEWCreate publication-quality books from Jupyter notebooks
Home Page: https://fastai.github.io/fastdoc/
License: Apache License 2.0
Create publication-quality books from Jupyter notebooks
Home Page: https://fastai.github.io/fastdoc/
License: Apache License 2.0
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?
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.
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?
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)
[NOTE]
====
This is a note with some https://github.com/fastai[link]
====
[NOTE]
====
This is a note with some [link](https://github.com/fastai)
====
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
fastdoc_numbered_list.ipynb
from this gist and place it in some folder, e.g. book
fastdoc_convert_all --path path/to/book --dest_path output
fastdoc 0.0.2
pandoc 2.3.1
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.
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?
cd path/to/fastdoc_sections_test.ipynb
mkdir images
fastdoc_convert_all --path ./ --dest_path convert_book
An fastdoc_sections_test.asciidoc
file with the following content
== Heading level 1
=== Heading level 2
==== Heading level 3
== Heading level 1
== Heading level 2
== Heading level 3
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.
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.
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?
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.
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!
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
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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.