Advice for placement of pre-"jb build" hook

[tlambert03]

Quick question. Apologies if I've missed this in he docs or other topics...

We have some scripts that render markdown files from content, and our build pipeline generally looks something like:

python scripts/prepare_docs.py
jb build docs

I'm wondering what you would advise for getting that script step to somehow be a part of jb build. If there's no built-in jupyter-book approach, would it make sense to include a sphinx local_extension (and if so, which sphinx hook would be most appropriate here?)

Thanks for any advice!

[choldgraf]

That's an interesting question - Sphinx definitely does have the flexibility for this kind of thing (by default, Sphinx is configured by a conf.py file, and that is often used to run arbitrary Python code to prep stuff before the actual build.

I guess one question is: what do you perceive as the benefit of bundling that pre-processing step with jupyter-book, vs having it as a second step? For example, since jupyter book uses Python, you could use a tool like nox to automate your build process. As an example, if you:

• Installed nox (pip install nox)

• Created a file called noxfile.py in your repository

• Added this to it:

  import nox
  nox.options.reuse_existing_virtualenvs = True  # re-use an environment instead of installing from scratch each time
     
  @nox.session
   def build(session):
       session.install("requirements.txt")  # Or however your book dependencies are defined
       session.run("python", "scripts/prepare_docs.py")
       session.run("jb", "build", docs")

Then you'd be able to one-line a book build with nox -s build (or even just nox since this is the only command listed).

[tlambert03]

Yes, currently I do have a one-liner (make docs) using a makefile, and nox would work nicely as well.
So it's not so much the one-liner I'm after... I guess it's more that some of our contributors (at napari) are aware that we use jupyter-book, and the possibility/temptation exists to try to build the docs using jb build, in which case they'd miss out on the extra critical logic in the makfile/noxfile. It's of course solvable with better communication amongst developers, but I was kind of looking for a setup that nobody could mess up regardless of how they built the docs :)

[choldgraf]

Right - so you basically imagine like a pre-build hook, and / or a post-build hook, that you could plug into as part of the build process?

Then there is always the sphinx events hooks but my gut tells me we don't want users to have to think about sphinx as much as possible

[tlambert03]

yep! that's exactly what I'm thinking. Definitely just a convenience (i.e., not without reasonable workarounds), but would help us eliminate those few cases where someone doesn't read the "how to build the docs" guide.
Thanks for your time :)