Try out the guide and provide feedback!

[choldgraf]

OK all - I've got a prototype of a CLI ready for people to try out! There is now a CLI for managing myst-parser, myst-nb, sphinx, and some of our extensions! You can invoke it like so:

jupyter-book build path/to/mybook

I put together some documentation in this repository that is built with this tool (my god it's so much easier than with Jekyll). It copies over some of the content from jupyterbook.org and adopts it for our build system.

https://beta.jupyterbook.org/

In addition, there is a little guide that should help people get started:

https://beta.jupyterbook.org/guide/01_overview.html

It would be great if folks could give this a shot and see what breaks, what looks wrong, etc. There are many things to improve upon, I'm sure!

Things you could give feedback about:

• Do the steps given in the documentation work?
• Is the documentation clear?
• Did anything unexpected happen?
• What do you think of the "book structure" we expect? (_toc.yml, _config.yml and content files)
• What do you think of the CLI? (note there are some extra things in here that aren't fully baked)
• How does the output look?
• How do the logs look? (we should probably find something cleaner than Sphinx logs to show people)
• Any features in the build system that you wish existed?

There are also some things we know are not yet in the CLI, here is a short list:

• Doesn't yet use jupyter-cache to grab outputs, so the outputs must be inside any notebooks that are read in
• Doesn't do markdown -> notebook conversion, so markdown files are "just" parsed as markdown.
• The theme still has a top nav-bar. Eventually this will be only a left sidebar.

It would be great if folks can start trying this out, opening issues, making PRs, etc!

cc @gregcaporaso @jstac, @mmcky, and @rossbar who mentioned they were interested in this

[jstac]

Thanks @choldgraf and @chrisjsewell. Love your work. Just wanted to say that before I start critiquing :-)

[rossbar]

I finally had a chance to give the CLI a try - I think it's great! I really like the "book-level-toc" design that Jupyter-Book uses and it's nice to have that feature along with the new (at least compared to Jupyter-Book 1.*) MyST/Sphinx components from the EBP as well.

#29 contains some quick fixups/suggestions from my first runthrough. I also have some notes from the runthrough: https://hackmd.io/6YNG5gm3TEO2ZXs1VlNluw?edit. Right now they're fairly rough and not all of the notes map directly back to the CLI (some are probably more related to the jupyterbook-theme, etc.) so I'm hesitant about cluttering things up with a bunch of new issues. If you have a chance to glance those over and think there is anything in there you'd like entered in the issue tracker, I'm happy to do so.

[choldgraf]

Thanks very much for the feedback! I'm glad you thought it was a good first shot :-)

A few specific responses to your points:

• I merged your PR - thanks!
• re: the TOC, I imagined we could port over chunks of https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/toc.py#L53 to have a jb toc path/to/book option. Would love to have a PR on that if you've got the time!
• re: building to PDF, I totally agree. That's is more @mmcky and @AakashGfude 's expertise so I'm hoping they'll have time to make improvements on the latex/PDF side soon!
• re: ghp-import I think there's some confusion there because those two steps are actually redundant. You can either directly upload your HTML as in the first step, or you can use ghp-import to do the upload. That should be clarified!
• FAQ: it should be CLI issues for now
• metadata: here is the latest convo: A myst-based 'ipynb' document structure  MyST-NB#12
• resizing: yeah we have a lot more work to do there :-)

[choldgraf]

gonna close this one as I think this round of feedback has now been incorporated