https://pantsbuild.org/ logo
Join Slack
Powered by
Curious if anyone knows of a plug-in to build Jupy...
# plugins
l
Curious if anyone knows of a plug-in to build Jupyter book docs?
b
l
Thanks! I think these are jupyter lab though right? I'm looking for anything that works with jupyter book https://github.com/executablebooks/jupyter-book Unless you mean these plugins might be a model for an approach?
b
Unless you mean these plugins might be a model for an approach?
Yes, it is a model, it does not answer your question directly.
If you are writing a book, I suggest that the libre software made by me: https://mogan.app
Here is the demo book: https://github.com/XmacsLabs/interactive-sicp Interactive SICP
l
Ahh cool thanks! Not actually writing a book. Just using it because I like the way it works for creating documentation in my repos that can easily be hosted on GitHub pages
b
If you writes a lot python snippet, juyter book seems to be a good solution.
👍 1
b
Hi @loud-laptop-89838, I am also looking for a Jupyter Book plugin for pants. I implemented the following yesterday: • https://github.com/OpenSaMD/OpenSaMD/blob/348053ed1b07b6d009beb8a6d548b6fb65bab275/docs/build.py • https://github.com/OpenSaMD/OpenSaMD/blob/348053ed1b07b6d009beb8a6d548b6fb65bab275/docs/BUILD Which allows me to run 
./pants run docs:build
And that then builds my docs: https://github.com/OpenSaMD/OpenSaMD/blob/348053ed1b07b6d009beb8a6d548b6fb65bab275/.github/workflows/main.yml#L50 However, this seems like "the wrong way"... I just can't seem to get my head around how to do this with a plugin though. --- I also suspect this might be a neat solution to the core teams docs questions that they've been discussing over at: https://docs.google.com/document/d/1bZE8PlF9oRzcPQz4-JUFr5vfD0LFHH4V3Nj2k221CFM/view --- By building the docs how I have above, it allows me to benefit from pants lock files: • https://github.com/OpenSaMD/OpenSaMD/blob/ecdae2e0aa75f73a565f056068ecfb69d847918e/3rdparty/python/requirements.txt#L4 • https://github.com/OpenSaMD/OpenSaMD/blob/ecdae2e0aa75f73a565f056068ecfb69d847918e/3rdparty/python/default.lock#L1501-L1506 But... it certainly feels like quite the "hacky" approach.
👀 2
l
Cool! I don't have time to read through this now, but I will soon and then get back to you on thoughts.
b
I don't know a thing about Jupyter, so this may be off-base, but fwiw this plugin was contributed last year: https://github.com/pantsbuild/pants-jupyter-plugin. Does it provide any helpful insight wrt this question?
b
Hi @busy-vase-39202, Unfortunately not. Jupyter Book is actually a sphinx wrapper. It is designed to make sphinx much, much easier to use. Allows sphinx documentation to be built with their extended version of markdown and/or notebooks.
So, if anything, a "sphinx" pants target would be closer to the mark.
b
Ohhh. We'd love to have sphinx integration.
👍 1
b
Yup, a huge bunch of people have migrated over from sphinx to jupyter book (and under the hood it's essentially the same). However it is much, much easier to use. I think it would be amazing if pants had a jupyter book target, and also used jupyter book for their own documentation.
b
We moved over toin-repo docs earlier in the year but got super busy and hadn't found time to setup sphinx. If JB is faster to setup, that would certainly be helpful.
h
Funny, we have been looking for a potential replacement for readme.com for the pantsbuild.org docs
Sounds like jupyter book might be worth a look
😊 1
l
@happy-kitchen-89482 @busy-vase-39202 take a look at the jupyter book website. I'm pretty sure it's built entirely using its own tool. The thing I like most is that you can use jupyter notebooks to create a page, which allows you to run python code. But you don't have to. You can also make pages entirely in markdown, you can mix and match.
@best-autumn-75351 it looks to me like you've likely already built it, but it's just not in plug-in format. If you want I'd be happy to collaborate on an installable plugin. Since it's your code, if you create a repo, I can work on turning it into a plug-in. Alternatively, if the Pants folks want to take this on for their own repo, presumably it could just be built into pants.
c
I like the idea of having executable examples directly in the docs.. 🙂
b
Me too. That sounds quite intriguing.
h
I like the look of their website, so this seems promising
b
@loud-laptop-89838 and @best-autumn-75351 if you'd be willing to lend us a hand and opinions on what the plugin should be, I suspect we can find a maintainer who'd like to collaborate with you on making it happen. How does that sound? Of course, if you're comfortable writing a plugin do feel free to proceed on your own. Just want you to know support is available if you need.
l
I'm always happy to be supported if that's possible. @best-autumn-75351 took the first steps so I will defer.
From my review of Simon's repo it looks like that jupyter book target is an implementation specific to that repo, e.g. builds the TOC based on file/folder structure. So an installable plugin would just have to look at the jupyter book API and make sure at least a core subset of those options are built in.
b
Hi @busy-vase-39202, @happy-kitchen-89482,@loud-laptop-89838, and anyone else interested in helping, would it work for us to go with an approach where we undergo development in my repo under an Apache license, and then, once we're happy with it, have it mainlined into pantsbuild?
And most certainly, having support from a pants maintainer would be absolutely amazing 🙂
l
@best-autumn-75351 the only thing about doing it as an in repo plugin is that others (eg me) can't use it without copying the code itself. Also we'd need to fork your repo to contribute. Would you be willing to set up a new repo for the jupyter book plug-in? Then you can add me and whoever else directly and I'll be able to more directly test and use it.
Then the plug-in can be directly installed and used by anyone.
b
Fair points, to fix the first issue I've just invited you as a collaborator on OpenSaMD. For the second point, I just added in a Flit based pyproject.toml within the "pant-plugin" directory, which allows me to publish the contents of that directory to the following package: https://pypi.org/project/opensamdpantsplugins/ See the following: https://github.com/OpenSaMD/OpenSaMD/tree/add-in-jupyterbook-pants-plugin/pants-plugin So hopefully that should fix both the "easy to use prior to being mainlined upstream" as well as the "easy to contribute" (as you won't need to fork) Given we're using a monorepo management tool... I find... I almost never need to "make another repo" 🙂
Also, @loud-laptop-89838, do you have an account PyPI? I can add you as a contributor to that package so that you're free to publish dev updates also, that way, whenever you update the code you can just go PyPI publish and then use it within your own repo.
h
That sounds like a good way to go about it. We'd very likely be happy to upstream it into the main pants repo when the time comes.
TBH writing it directly in the pants repo is also fine
l
Ok. Works for me! I'll get acquainted shortly.
h
@fresh-cat-90827's pending plugin writing tutorial may be handy: https://github.com/pantsbuild/pants/pull/17732
b
Kk, let's go with directly into the pants repo. Within the 
pants.toml
file in our own repos might it be able to be possible to do something like setting the 
pants_version
to a git commit hash corresponding to a commit hash on the upstream pantsbuild/pants repo so that we can utilise the version of pants (with its in-development plugins) in our own repos?
@happy-kitchen-89482, unfortunately I am quite stumped with how to get started. As a bit of a "hello world" I'd be looking to be able to replicate the following within a pants plugin format: https://github.com/OpenSaMD/OpenSaMD/blob/d53133ce42126ef1bfa323dec150d649cd73f1f4/docs/build.py#L36-L45 To start with, I wouldn't need all of the bells and whistles, just something that works initially, that can then be iterated on from there...
c
Regarding using bleeding edge Pants in other projects, you can while developing Pants try it out in another project (in a sibling directory to where Pants is checked out) using this pants_from_sources script another option, once a PR has landed on 
main
, you can set 
PANTS_SHA
(see the `pants` setup script )
b
Beautiful, that sounds perfect. Thank you.
l
Ok great. I'm good either way. If we're putting it directly in pants then it's just be good to get direction on where to put it (pants-plugins folder)? Also, to collaborate efficiently @best-autumn-75351 do you want to work together on a single fork? Rather than each of us creating one.
c
Plugins go into something like: 
src/python/pants/backend/jupyter/
(or perhaps 
src/python/pants/backend/python/jupyter
if it’ll require the python backend, I think 🙂 )
Then, during development we can offer it as a preview plugin by placing the 
register.py
file in 
src/python/pants/backend/experimental/python/jupyter/register.py
or similar..
l
perfect, although this isn't jupyter, so it'd be 
**/juputer-book/*
?
👍 2
b
Is that a typo? Given that it's to be a registration name, just want to confirm...
l
@busy-vase-39202 typo where? I put asterisks to mean that it would be in 
src/python/pants/backend/python/jupyter_book
. Does that make sense?
b
I meant juputur vs jupyter
✅ 1
b
Also, to collaborate efficiently @best-autumn-75351 do you want to work together on a single fork?
-- @loud-laptop-89838 Sounds good, let's use this one: https://github.com/OpenSaMD/pants
Also, @loud-laptop-89838 and others let's move our discussion over to: https://github.com/pantsbuild/pants/discussions/17789
➕ 1
👍 2
11 Views
Open in Slack
PreviousNext
Powered by