Comments (5)
lexnederbragt
commented on May 31, 2024
Jupyterbook has been on my radar for a while. I support this issue wholeheartedly! I can be a test user if that is of interest.
from doconce.
aless80
commented on May 31, 2024
Thank you Lex!
Some notes about this first implementation.
Examples:
# Help on terminal
doconce jupyterbook --help
Usage: doconce jupyterbook filename [options]
Create files for Jupyter Book version: 0.8
Example: doconce jupyterbook filename.do.txt --sep=section
Try 'doconce jupyterbook --help' for more information.
-h Show this help page
--help Show this help page
--sep=... Specify separator for DocOnce file into jupyter-book chapters. [chapter|section|subsection]
--dest=... Destination folder for the content
--dest_toc=... Destination folder for the _toc.yml file
--titles=... File with page titles, i.e. titles in TOC on the left side of the page. Default is 'auto': assign titles based on the separator headers
# Execute on a DocOnce file using the sep, dest, and dest_toc options
doconce jupyterbook mybook.do.txt --sep=section \
--dest=/home/someuser/mybook --dest_toc=/home/someuser/mybook
#Also use the title option
doconce jupyterbook mybook.do.txt --sep=subsection \
--dest=/home/someuser/mybook --dest_toc=/home/someuser/mybook \
--titles=/home/someuser/mybook/file_with_titles.txt
#doconce jupyter also accept "general" options
doconce jupyterbook mybook.do.txt --sep=chapter \
--examples_as_exercises --allow_refs_to_external_docs
Possible pitfalls: The points 2 and 3 listed in the jupyterbook documentation, i.e. Use only one top-level header and Headers should increase linearly.
According to the first point Files must have a title in the jupyterbook docs, the jupyter-book chapters/parts (i.e. the files that compose a jupyter-book) must have a title. The title is taken from the headers in the DocOnce file, but if none is found the title will be the basename of the DocOnce file e.g. 03_mybook.
I added an example of this functionality to the tests. This allowed me to discovered a few problems that I had to iron out. In particular, to make this work on test/testdoc.do.txt I had to use the DocOnce options --examples_as_exercises --allow_refs_to_external_docs. The second one is needed because references (e.g. ref{sec:theory}) end up in different files. The good thing is that both options were suggested by the DocOnce's output when DocOnce failed. I also had to ignore separators that are within code (the !bc and !eb directories).
To make jupyter-book work I had to do some troubleshooting, e.g. upgrading Sphinx and jupyter-client. We might have to update the software requirements accordingly.
from doconce.
aless80
commented on May 31, 2024
Pushed #32 , which should give more flexibility when using the title option.
After a discussion with a DocOnce user, I am considering to extend the --sep option or create a couple of ones such as --sep_chapter, --sep_section. The aim would be to let a user automatically create jupyter-book books with chapters sub-divided in sections. Note that jupyter-book also has the concept of parts, which are collection of chapters.
from doconce.
aless80
commented on May 31, 2024
Pushed #33 , which introduces the subdivision of jupyter-books in sections using the --sep_section option.
As before, the --sep splits a DocOnce document in Jupyter-book chapters. The new --sep_section option subdivides chapters in Jupyter-book sections.
Users can pass custom titles to the --titles=<file> option as before. To help writing the titles down I created the --show_titles option, which prints out the titles detected in headers of the DocOnce file.
Examples:
# Help on terminal
doconce jupyterbook --help
Usage: doconce jupyterbook filename [options]
Create files for Jupyter Book version: 0.8
Example: doconce jupyterbook filename.do.txt --sep=section
Try 'doconce jupyterbook --help' for more information.
-h Show this help page
--help Show this help page
--sep=... Specify separator for DocOnce file into jupyter-book chapters. [chapter|section|subsection]
--sep_section=... Specify separator for DocOnce file into jupyter-book sections. [chapter|section|subsection], optional
--dest=... Destination folder for the content
--dest_toc=... Destination folder for the _toc.yml file
--show_titles Print out the titles detected based on the separator headers. This can be helpful for the file passed to the --titles option
--titles=... File with page titles, i.e. titles in TOC on the left side of the page. Default is 'auto': assign titles based on the separator headers
# Show the titles detected on a DocOnce file using the --sep and --sep_sections options
doconce jupyterbook testdoc --show_titles --sep=chapter --sep_section=subsection
#this shows a list of titles that can be used in a title file
# Execute on a DocOnce file using the sep, sep_sections options
doconce jupyterbook testdoc --sep=chapter --sep_section=subsection dest_toc=$PWD dest_toc=$PWD/content
# Same, use a title file and some other DocOnce options
doconce jupyterbook testdoc --sep=chapter --sep_section=subsection dest_toc=$PWD dest_toc=$PWD/content \
--titles=titles.txt \
--allow_refs_to_external_docs --examples_as_exercises
from doconce.
aless80
commented on May 31, 2024
Close
from doconce.
Related Issues (20)
- Speaker notes in deck slides HOT 2
- TITLE/AUTHOR/DATE cause empty markdown cell at top of ipynb output HOT 1
- `print(type(x))` gives no output in html HOT 1
- New feature: abort on error with --execute HOT 7
- Create an answer book in ipynb HOT 5
- New feature: enable execution in a different folder HOT 7
- Figures with caption inside admonitions do not work HOT 1
- Empty markdown cells in ipynb
- Remove `Figure 1` label in html slides when no caption given HOT 4
- Github Actions on the doconce repo time out
- Create notebook cell id based on cell content
- Python 1 HOT 1
- TOC title in html and ipynb have different margins HOT 2
- Miras
- code execution for html should be skipped when py-out present
- Formatting of py-out block in html HOT 1
- Localization of doconce HOT 2
- DocOnce and Beamer document with animation HOT 1
- Compatiliblity with regex 2022.10.31 HOT 1
- Pointing to solutions for installation problems HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from doconce.