Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

modularizing the bage building and beefing up single page building #344

Merged
merged 10 commits into from
Sep 26, 2019
Merged

modularizing the bage building and beefing up single page building #344

merged 10 commits into from
Sep 26, 2019

Conversation

choldgraf
Copy link
Collaborator

@choldgraf choldgraf commented Sep 20, 2019 •
edited
Loading

This PR makes the single-page HTML building a bit more modular and lays some foundation for making it easier to build a single page's HTML from book content. It does the following main things:

  • the build_html function now takes a NotebookNode as input, and outputs raw HTML
  • there's now a write_html function that then takes the output HTML and writes it to disk
  • re-working some of the book building process so this still works
  • the CLI command for building one page now uses the above build_html function and adds in the CSS / SCSS / js needed to make the page render normally as a standalone page
  • Moving some of the JS scripts that don't depend on Jekyll variables into the assets/ folder instead of _includes/. This should speed up builds and make it clearer what depends on the Jekyll site.
  • Moving some SCSS and Javascript files to a page/ sub-folder, to make it clearer what should be self-contained within a page and what should be specific to a whole book.

There are a lot of files changed in this one, mostly because of the file location rearranging. However, it shouldn't change the behavior of building books (building a single page now behaves a bit differently).

@emdupre you might be interested in this because it's trying to further disentangle building a whole book from building a single page. Does anything about the artifact preview look off to you?

In addition to the doc below, here are examples of single-page HTML outputs:

https://1727-137292803-gh.circle-artifacts.com/0/html_singlepage/jupytext.html
https://1727-137292803-gh.circle-artifacts.com/0/html_singlepage/markdown.html
https://1727-137292803-gh.circle-artifacts.com/0/html_singlepage/notebooks.html

@choldgraf choldgraf changed the title modularizing the bage building and beefing up single page building [WIP] modularizing the bage building and beefing up single page building Sep 20, 2019
@choldgraf choldgraf mentioned this pull request Sep 20, 2019
Merged
@choldgraf choldgraf force-pushed the page_html branch 8 times, most recently from e7c671c to ec0b57f Compare September 25, 2019 16:49
@choldgraf choldgraf force-pushed the page_html branch 2 times, most recently from 49646a4 to f7f24af Compare September 25, 2019 21:38
@choldgraf choldgraf changed the title [WIP] modularizing the bage building and beefing up single page building modularizing the bage building and beefing up single page building Sep 26, 2019
@choldgraf
Copy link
Collaborator Author

OK, tests are happy and the new netlify build is working as well. None of this should change what the user experiences or how the sites look (mostly), but there's a fair bit of rearranging under the hood (which is why there are so many modified files). If anybody has thoughts give them now!

@choldgraf
Copy link
Collaborator Author

maybe @SamLau95 has thoughts on this one as well - any thoughts on the SCSS restructuring? The goal is to separate out the pieces for "building a page" from "building a book", though hopefully without increasing the cognitive burden too much

@emdupre
Copy link
Collaborator

emdupre commented Sep 26, 2019

I'll look at this first thing tomorrow morning !! Thanks for the ping

emdupre
emdupre reviewed Sep 26, 2019
View reviewed changes
Copy link
Collaborator

@emdupre emdupre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks really good ! I had one question on whether users can add in their own JS / CSS, much as we do in the full book.

I'm also a little confused in that it seems that the CSS for the page converted from the notebook is different than the CSS for the page converted from the Jupytext / Markdown files ? Not sure if it's just the chosen exemplars or if they're genuinely different, looking at e.g. the title and byline.

jupyter_book/page/page.py Outdated
return html, resources


def page_head():
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be worthwhile to also let users add in their own JS / CSS here, as we do in the full book ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah that's a good idea - lemme give it a shot

@choldgraf
Copy link
Collaborator Author

choldgraf commented Sep 26, 2019 •
edited
Loading

Thanks for the feedback @emdupre! I just pushed a commit with the ability to add custom CSS and JS in the write_page function + some tests for it.

re: page for notebook vs. jupytext, I don't believe the CSS is different between the two. The main thing that's different there is a function I was playing around with to embed a <div for a page title and author if it was found in the notebook.

That said, I think this PR is already too busy, so I'm going to remove that functionality for now and I opened up #362 to talk about it!

Any feedback for other stuff?

@SamLau95
Copy link
Collaborator

Looks good to me! To clarify, this PR lets us publish single notebooks as standalone webpages instead of publishing notebooks as pages within a larger book?

@choldgraf
Copy link
Collaborator Author

@SamLau95 yep exactly. Basically it tries to factor out the "build a single page's HTML" steps into a sub-module. Now the book uses that submodule for each page, and if you want to build a page by itself, then you can add a <head> to it that links the proper subset of CSS and JS

emdupre
emdupre approved these changes Sep 26, 2019
View reviewed changes
Copy link
Collaborator

@emdupre emdupre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This LGTM ! 🎉 Really excited to take it for a spin !

@choldgraf
Copy link
Collaborator Author

ok...I'm gonna merge this one away and we can see how it breaks :-)

@choldgraf choldgraf merged commit 3808625 into jupyter-book:master Sep 26, 2019
@choldgraf choldgraf deleted the page_html branch September 26, 2019 19:21
@choldgraf choldgraf added the maintenance Generic under-the-hood improvements to code and docs label Oct 2, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@emdupre emdupre emdupre approved these changes

Assignees
No one assigned
Labels
maintenance Generic under-the-hood improvements to code and docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@choldgraf @emdupre @SamLau95